Skip to content

Commit

Permalink
Simplify the README, add Development guide (GoogleCloudPlatform#441)
Browse files Browse the repository at this point in the history 
* Simply the readme

* Copy paste mishap

* typo fix
  • Loading branch information
@askmeegs
askmeegs authored Nov 13, 2020
1 parent 9636096 commit 402d1c5
Show file tree
Hide file tree
Showing 3 changed files with 281 additions and 253 deletions.
350 changes: 97 additions & 253 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
</p>


![Continuous Integration](https://github.com/GoogleCloudPlatform/microservices-demo/workflows/Continuous%20Integration%20-%20Master/Release/badge.svg)


**Online Boutique** is a cloud-native microservices demo application.
Online Boutique consists of a 10-tier microservices application. The application is a
Expand All @@ -11,7 +13,7 @@ add them to the cart, and purchase them.

**Google uses this application to demonstrate use of technologies like
Kubernetes/GKE, Istio, Stackdriver, gRPC and OpenCensus**. This application
works on any Kubernetes cluster (such as a local one), as well as Google
works on any Kubernetes cluster, as well as Google
Kubernetes Engine. It’s **easy to deploy with little to no configuration**.

If you’re using this demo, please **★Star** this repository to show your interest!
Expand All @@ -28,10 +30,96 @@ Looking for the old Hipster Shop frontend interface? Use the [manifests](https:/
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [![Screenshot of store homepage](./docs/img/online-boutique-frontend-1.png)](./docs/img/online-boutique-frontend-1.png) | [![Screenshot of checkout screen](./docs/img/online-boutique-frontend-2.png)](./docs/img/online-boutique-frontend-2.png) |

## Service Architecture

**Online Boutique** is composed of many microservices written in different
languages that talk to each other over gRPC.
## Quickstart (GKE)

1. **[Create a Google Cloud Platform project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)** or use an existing project. Set the `PROJECT_ID` environment variable and ensure the Google Kubernetes Engine API is enabled.

```
PROJECT_ID="<your-project-id>"
gcloud services enable container --project ${PROJECT_ID}
```

2. **Clone this repository.**

```
git clone https://github.com/GoogleCloudPlatform/microservices-demo.git
cd microservices-demo
```

3. **Create a GKE cluster.**

```
ZONE=us-central1-b
gcloud container clusters create onlineboutique \
--project=${PROJECT_ID} --zone=${ZONE} \
--machine-type=e2-standard-2 --num-nodes=4
```

4. **Deploy the sample app to the cluster.**

```
kubectl apply -f ./release/kubernetes-manifests.yaml
```

5. **Wait for the Pods to be ready.**

```
kubectl get pods
```

After a few minutes, you should see:

```
NAME READY STATUS RESTARTS AGE
adservice-76bdd69666-ckc5j 1/1 Running 0 2m58s
cartservice-66d497c6b7-dp5jr 1/1 Running 0 2m59s
checkoutservice-666c784bd6-4jd22 1/1 Running 0 3m1s
currencyservice-5d5d496984-4jmd7 1/1 Running 0 2m59s
emailservice-667457d9d6-75jcq 1/1 Running 0 3m2s
frontend-6b8d69b9fb-wjqdg 1/1 Running 0 3m1s
loadgenerator-665b5cd444-gwqdq 1/1 Running 0 3m
paymentservice-68596d6dd6-bf6bv 1/1 Running 0 3m
productcatalogservice-557d474574-888kr 1/1 Running 0 3m
recommendationservice-69c56b74d4-7z8r5 1/1 Running 0 3m1s
redis-cart-5f59546cdd-5jnqf 1/1 Running 0 2m58s
shippingservice-6ccc89f8fd-v686r 1/1 Running 0 2m58s
```

7. **Access the web frontend in a browser** using the frontend's `EXTERNAL_IP`.

```
kubectl get service frontend-external | awk '{print $4}'
```

*Example output - do not copy*

```
EXTERNAL-IP
<your-ip>
```

**Note**- you may see `<pending>` while GCP provisions the load balancer. If this happens, wait a few minutes and re-run the command.

8. [Optional] **Clean up**:

```
gcloud container clusters delete onlineboutique \
--project=${PROJECT_ID} --zone=${ZONE}
```

## Other Deployment Options

- **Workload Identity**: [See these instructions.](docs/workload-identity.md)
- **Istio**: [See these instructions.](docs/service-mesh.md)
- **Anthos Service Mesh**: ASM requires Workload Identity to be enabled in your GKE cluster. [See the workload identity instructions](docs/workload-identity.md) to configure and deploy the app. Then, use the [service mesh guide](/docs/service-mesh.md).
- **non-GKE clusters (Minikube, Kind)**: see the [Development Guide](/docs/development-guide.md)


## Architecture

**Online Boutique** is composed of 11 microservices written in different
languages that talk to each other over gRPC. See the [Development Principles](/docs/development-principles.md) doc for more information.

[![Architecture of
microservices](./docs/img/architecture-diagram.png)](./docs/img/architecture-diagram.png)
Expand Down Expand Up @@ -62,7 +150,7 @@ Find **Protocol Buffers Descriptions** at the [`./pb` directory](./pb).
- **[Istio](https://istio.io):** Application works on Istio service mesh.
- **[OpenCensus](https://opencensus.io/) Tracing:** Most services are
instrumented using OpenCensus trace interceptors for gRPC/HTTP.
- **[Stackdriver APM](https://cloud.google.com/stackdriver/):** Many services
- **[Cloud Operations (Stackdriver)](https://cloud.google.com/products/operations):** Many services
are instrumented with **Profiling**, **Tracing** and **Debugging**. In
addition to these, using Istio enables features like Request/Response
**Metrics** and **Context Graph** out of the box. When it is running out of
Expand All @@ -73,255 +161,11 @@ Find **Protocol Buffers Descriptions** at the [`./pb` directory](./pb).
job that creates realistic usage patterns on the website using
[Locust](https://locust.io/) load generator.

## Installation

We offer the following installation methods:

1. **Running locally** (~20 minutes) You will build
and deploy microservices images to a single-node Kubernetes cluster running
on your development machine. There are three options to run a Kubernetes
cluster locally for this demo:
- [Minikube](https://github.com/kubernetes/minikube). Recommended for
Linux hosts (also supports Mac/Windows).
- [Docker for Desktop](https://www.docker.com/products/docker-desktop).
Recommended for Mac/Windows.
- [Kind](https://kind.sigs.k8s.io). Supports Mac/Windows/Linux.

1. **Running on Google Kubernetes Engine (GKE)** (~30 minutes) You will build,
upload and deploy the container images to a Kubernetes cluster on Google
Cloud.

1. **Using pre-built container images:** (~10 minutes, you will still need to
follow one of the steps above up until `skaffold run` command). With this
option, you will use pre-built container images that are available publicly,
instead of building them yourself, which takes a long time).

### Prerequisites

- kubectl (can be installed via `gcloud components install kubectl`)
- Local Kubernetes cluster deployment tool:
- [Minikube (recommended for
Linux)](https://kubernetes.io/docs/setup/minikube/)
- [Docker for Desktop (recommended for Mac/Windows)](https://www.docker.com/products/docker-desktop)
- It provides Kubernetes support as [noted
here](https://docs.docker.com/docker-for-mac/kubernetes/)
- [Kind](https://github.com/kubernetes-sigs/kind)
- [skaffold]( https://skaffold.dev/docs/install/) ([ensure version ≥v1.10](https://github.com/GoogleContainerTools/skaffold/releases))
- Enable GCP APIs for Cloud Monitoring, Tracing, Debugger:
```
gcloud services enable monitoring.googleapis.com \
cloudtrace.googleapis.com \
clouddebugger.googleapis.com
```
### Option 1: Running locally
> 💡 Recommended if you're planning to develop the application or giving it a
> try on your 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 CPU's
- 4.0 GiB memory
- 32 GB disk space
```shell
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:
```shell
kind create cluster
```
2. Run `kubectl get nodes` to verify you're connected to “Kubernetes on Docker”.
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. Access the web frontend through your browser
- **Minikube** requires you to run a command to access the frontend service:
```shell
minikube service frontend-external
```
- **Docker For Desktop** should automatically provide the frontend at http://localhost:80
- **Kind** does not provision an IP address for the service.
You must run a port-forwarding process to access the frontend at http://localhost:8080:
```shell
kubectl port-forward deployment/frontend 8080:8080
```
### Option 2: Running on Google Kubernetes Engine (GKE)
> 💡 Recommended if you're using Google Cloud Platform and want to try it on
> a realistic cluster. **Note**: If your cluster has Workload Identity enabled,
> [see these instructions](/docs/workload-identity.md)
1. Create a Google Kubernetes Engine cluster and make sure `kubectl` is pointing
to the cluster.
```sh
gcloud services enable container.googleapis.com
gcloud services enable cloudprofiler.googleapis.com
```
```sh
gcloud container clusters create demo --enable-autoupgrade \
--enable-autoscaling --min-nodes=3 --max-nodes=10 --num-nodes=5 --zone=us-central1-a
```
```
kubectl get nodes
```
2. Enable Google Container Registry (GCR) on your GCP project and configure the
`docker` CLI to authenticate to GCR:
```sh
gcloud services enable containerregistry.googleapis.com
```
```sh
gcloud auth configure-docker -q
```
3. In the root of this repository, run `skaffold run --default-repo=gcr.io/[PROJECT_ID]`,
where [PROJECT_ID] is your GCP project ID.
This command:
- builds the container images
- pushes them to GCR
- 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](https://console.cloud.google.com/flows/enableapi?apiid=cloudbuild.googleapis.com),
then run `skaffold run -p gcb --default-repo=gcr.io/[PROJECT_ID]` instead.
4. Find the IP address of your application, then visit the application on your
browser to confirm installation.
kubectl get service frontend-external
### Option 3: Using Pre-Built Container Images
> 💡 Recommended if you want to deploy the app faster in fewer steps to an
> existing cluster.
**NOTE:** If you need to create a Kubernetes cluster locally or on the cloud,
follow "Option 1" or "Option 2" until you reach the `skaffold run` step.
This option offers you pre-built public container images that are easy to deploy
by deploying the [release manifest](./release) directly to an existing cluster.
**Prerequisite**: a running Kubernetes cluster (either local or on cloud).
1. Clone this repository, and go to the repository directory
1. Run `kubectl apply -f ./release/kubernetes-manifests.yaml` to deploy the app.
1. Run `kubectl get pods` to see pods are in a Ready state.
1. Find the IP address of your application, then visit the application on your
browser to confirm installation.
```sh
kubectl get service/frontend-external
```

### Option 4: Deploying on a Istio-enabled GKE cluster

> **Note:** if you followed GKE deployment steps above, run `skaffold delete` first to delete what's deployed.
1. Create a GKE cluster (described in "Option 2").

2. Use the [Istio on GKE add-on](https://cloud.google.com/istio/docs/istio-on-gke/installing)
to install Istio to your existing GKE cluster.

```sh
gcloud beta container clusters update demo \
--zone=us-central1-a \
--update-addons=Istio=ENABLED \
--istio-config=auth=MTLS_PERMISSIVE
```

3. (Optional) Enable Stackdriver Tracing/Logging with Istio Stackdriver Adapter
by [following this guide](https://cloud.google.com/istio/docs/istio-on-gke/installing#enabling_tracing_and_logging).

4. Install the automatic sidecar injection (annotate the `default` namespace
with the label):

```sh
kubectl label namespace default istio-injection=enabled
```

5. Apply the manifests in [`./istio-manifests`](./istio-manifests) directory.
(This is required only once.)

```sh
kubectl apply -f ./istio-manifests
```

6. In the root of this repository, run `skaffold run --default-repo=gcr.io/[PROJECT_ID]`,
where [PROJECT_ID] is your GCP project ID.

This command:

- builds the container images
- pushes them to GCR
- 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](https://console.cloud.google.com/flows/enableapi?apiid=cloudbuild.googleapis.com),
then run `skaffold run -p gcb --default-repo=gcr.io/[PROJECT_ID]` instead.

7. Run `kubectl get pods` to see pods are in a healthy and ready state.

8. Find the IP address of your Istio gateway Ingress or Service, and visit the
application.

```sh
INGRESS_HOST="$(kubectl -n istio-system get service istio-ingressgateway \
-o jsonpath='{.status.loadBalancer.ingress[0].ip}')"
echo "$INGRESS_HOST"
```

```sh
curl -v "http://$INGRESS_HOST"
```

### Option 5: Deploying on a Workload Identity-enabled GKE cluster

See [this doc](/docs/workload-identity.md).

### Cleanup

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

If you've deployed the application with `kubectl apply -f [...]`, you can
run `kubectl delete -f [...]` with the same argument to clean up the deployed
resources.
If you would like to contribute features or fixes to this app, see the [Development Guide](/docs/development-guide.md) on how to build this demo locally.

## Conferences featuring Online Boutique
## Demos featuring Online Boutique

- [Google Cloud Next'18 London – Keynote](https://youtu.be/nIq2pkNcfEI?t=3071)
showing Stackdriver Incident Response Management
Expand All @@ -334,4 +178,4 @@ resources.

---

This is not an official Google project.
This is not an official Google project.
Loading

0 comments on commit 402d1c5

Please sign in to comment.