Guestbook revisions + Minikube Default Frontend Service #46
Conversation
k8s-ci-robot
added
the
cncf-cla: yes
guestbook/README.md
Outdated
| - [Troubleshooting](#troubleshooting) | ||
| - [Appendix: Accessing the guestbook site externally](#appendix-accessing-the-guestbook-site-externally) | ||
| - [Google Compute Engine External Load Balancer Specifics](#google-compute-engine-external-load-balancer-specifics) | ||
| **Note:** If you are using a [Google Container Engine](https://cloud.google.com/container-engine/) installation, please read [Create a Guestbook with Redis and PHP](https://cloud.google.com/container-engine/docs/tutorials/guestbook) instead. The basic concepts are the same, but the walkthrough is tailored to a Container Engine setup. |
There was a problem hiding this comment.
I think we should delete such vendor-specific notes.
guestbook/README.md
Outdated
| <!-- EXCLUDE_FROM_DOCS END --> | ||
|
|
||
| This example shows how to build a simple, multi-tier web application using Kubernetes and [Docker](https://www.docker.com/). | ||
| {% capture overview %} | ||
| This tutorial shows you how to build a simple, multi-tier web application using Kubernetes and [Docker](https://www.docker.com/). This example consists of the following: |
guestbook/README.md
Outdated
| **Table of Contents** | ||
| <!-- BEGIN MUNGE: GENERATED_TOC --> | ||
| * a web frontend | ||
| * a [Redis](https://redis.io/) master for storage |
There was a problem hiding this comment.
a single-instance redis master to store guestbook entries
guestbook/README.md
Outdated
| <!-- BEGIN MUNGE: GENERATED_TOC --> | ||
| * a web frontend | ||
| * a [Redis](https://redis.io/) master for storage | ||
| * a replicated set of Redis slaves. |
There was a problem hiding this comment.
multiple replicated redis instances
OR
multiple replicated redis instances, used to serve reads
I think "replicated set" is capturing the fact that this was once a ReplicaSet. but not antymore.
guestbook/README.md
Outdated
| The example consists of: | ||
| {% capture objectives %} | ||
| * Start up a redis master. | ||
| * Start up a redis slave. |
guestbook/README.md
Outdated
|
|
||
| **Table of Contents** | ||
| <!-- BEGIN MUNGE: GENERATED_TOC --> | ||
| * a web frontend |
guestbook/README.md
Outdated
|
|
||
| ### Quick Start | ||
| ### Creating the Redis Master Deployment | ||
| 1. `cd` to the folder you saved the `.yaml.` files. |
There was a problem hiding this comment.
Rewrite as:
- Launch a terminal window in the directory you downloaded the manifest files
- Apply the Redis Master Deployment to the cluster using the
redis-master-deployment.yamlfile:
ditto for other steps.
guestbook/README.md
Outdated
| service "frontend" created | ||
| deployment "frontend" created | ||
| ```shell | ||
| kubectl create -f redis-master-deployment.yaml |
There was a problem hiding this comment.
Let's switch to using kubectl apply. It has more benefits over kubectl create ,especially when updating.
guestbook/README.md
Outdated
|
|
||
| Alternatively, you can start the guestbook by running: | ||
| {:start="3"} | ||
| 3. Get the Pods to verify that the Redis Master Pod is running: |
There was a problem hiding this comment.
Get the Pods → Query the list of Pods
| @@ -6,6 +6,8 @@ metadata: | |||
| app: guestbook | |||
| tier: frontend | |||
| spec: | |||
| # comment or delete the following line if you want to use a LoadBalancer | |||
| type: NodePort | |||
There was a problem hiding this comment.
we'll need to update instructions on https://cloud.google.com/container-engine/docs/tutorials/guestbook#expose_frontend_on_an_external_ip_address after merging this.
maybe at some point we should have 2 service files (or a single file that describes both a NodePort service as well as a LoadBalancer). This way, minikube people can get it to work as well as people trying it out on the cloud.
There was a problem hiding this comment.
Ah, I hadn't considered that. It looks like Minikube will just output <pending> for EXTERNAL-IP if I leave both type: NodePort and type: LoadBalancer uncommented, but I can otherwise still complete the tutorial.
Does including both types affect any for the Container Engine side?
There was a problem hiding this comment.
@cody-clark you can try, but I think we can't have both in the same YAML file. (I'm not sure it's a good practice to do so either.)
What would work in both platforms is to have 2 services (guestbook, guestbook-external) in a single file or separate files, but that would be more confusing. For now, let's keep it as is and I will update GKE tutorial.
guestbook/README.md
Outdated
|
|
||
| ### Prerequisites | ||
| ## Start up the Redis Master |
There was a problem hiding this comment.
nit: always use empty line after headings to prevent rendering nuances in different markdown parsers
guestbook/README.md
Outdated
| tier: backend | ||
| ``` | ||
| ### Creating the Redis Master Service | ||
| The guestbook applications needs to communicate to the Redis master to write its data. You need to apply a [Service](https://kubernetes.io/docs/concepts/services-networking/service/) to proxy the traffic to the Redis master Pod. A Service defines a set of Pods and a policy to access them. |
There was a problem hiding this comment.
a policy to access them.
Service doesn't define a policy. Consider removing that part.
guestbook/README.md
Outdated
|
|
||
| #### Create a Service | ||
| kubectl apply -f redis-master-service.yaml |
There was a problem hiding this comment.
you have too much space, the rendered code block has 4 spaces at the beginning, throughout the doc. Please start all code block lines at 4 spaces.
guestbook/README.md
Outdated
|
|
||
| #### Create a Deployment | ||
| kubectl apply -f redis-slave-deployment.yaml |
There was a problem hiding this comment.
has 1 extra space character at the beginning (click View button for this file on github UI)
guestbook/README.md
Outdated
| redis-slave-2005841000-phfv9 0/1 ContainerCreating 0 6s | ||
|
|
||
| ### Creating the Redis Slave Service | ||
| The guestbook application needs to communicate to Redis workers to read data. To make the Redis workers discoverable, you need to set up a Service. A Service provides transparent load balancing to a set of Pods. |
There was a problem hiding this comment.
slave vs. workers: You need to unify the terminology. It's ok if you decide to change slave work (incl. filenames) to worker.
I already use the word worker and not slave (that only comes from imported files/filenames) in GKE guestbook: https://cloud.google.com/container-engine/docs/tutorials/guestbook
guestbook/README.md
Outdated
|
|
||
| #### Optional Interlude | ||
| ## Set up and Expose the Guestbook Frontend | ||
| This tutorial uses a simple PHP server that is configured to talk to either the slave or master Services, depending on whether the client request is a read or a write. It exposes a simple JSON interface, and serves a jQuery-Ajax-based UX. |
There was a problem hiding this comment.
This is a bit too much detailed for anyone following the tutorial. suggested rewrite:
The guestbook application has a web frontend serving the HTTP requests written in PHP. It is configured to connect to the
redis-masterservice for write requests and theredis-slaveservice for read requests.
guestbook/README.md
Outdated
| #### Finding a Service | ||
|
|
||
| Kubernetes supports two primary modes of finding a Service — environment variables and DNS. | ||
| {:start="2"} |
There was a problem hiding this comment.
there's a chance you might not need the {:start="2"} stuff. Consider the following markdown with quotes etc:
Rendering:
-
Hello hello hello
-
Hello this will be a quote:
quote quote
-
here's some code yo:
code code i love coding -
last item (note how I still say 1 and it's still all numbered correctly)
Source:
1. Hello hello hello
1. Hello this will be a quote:
> quote quote
1. here's some code yo:
code code
i love coding
1. last item (note how I still say 1 and it's still all numbered correctly)
not a big deal, just try it out on staging container (or in a separate PR to docs and see netlify staging). I've got a feeling like we can get rid of jekyll-specific stuff like this and rely more on Markdown semantics. It could be hard to get how many spaces you exactly need to add quotes/code blocks in a list, but it's not impossible.
guestbook/README.md
Outdated
|
|
||
| 1. Run the following command to delete all Pods, Deployments, and Services. | ||
|
|
||
| kubectl delete deployments,services -l "app in (redis, guestbook)" |
There was a problem hiding this comment.
this is REALLY cool actually TIL you can use comma like that, but it's simultaneously super confusing.
Let's expand this as:
kubectl delete deployment -l app=redis
kubectl delete service -l app=redis
kubectl delete deployment -l app=guestbook
kubectl delete service -l app=guestbook
the result should be the same.
guestbook/README.md
Outdated
|
|
||
| #### Create a Deployment | ||
| Although the Redis master is a single pod, you can make it highly available to meet traffic demands by adding replica Redis workers. |
There was a problem hiding this comment.
slave vs worker: please unify the terminology. either rename files (and name: fields) to worker, or just call them slave throughout the tutorial)
guestbook/README.md
Outdated
|
|
||
| ### Creating the Guestbook Frontend Deployment | ||
|
|
||
| 1. Apply the frontend Deployment from the following `frontend-deployment.yaml` file: | ||
|
|
||
| kubectl apply -f frontend-deployment.yaml | ||
|
|
||
| {% include code.html language="yaml" file="frontend-deployment.yaml" ghlink="/docs/tutorials/docs/tutorials/stateless-application/frontend-deployment.yaml" %} | ||
| {% include code.html language="yaml" file="frontend-deployment.yaml" ghlink="/docs/tutorials/docs/tutorials/stateless-application/frontend-deployment.yaml" %} |
There was a problem hiding this comment.
/docs/tutorials/docs/tutorials/ is incorrect
guestbook/README.md
Outdated
|
|
||
| {% include code.html language="yaml" file="redis-master-deployment.yaml" ghlink="/docs/tutorials/docs/tutorials/stateless-application/redis-master-deployment.yaml" %} | ||
| {% include code.html language="yaml" file="redis-master-deployment.yaml" ghlink="/docs/tutorials/docs/tutorials/stateless-application/redis-master-deployment.yaml" %} |
There was a problem hiding this comment.
- /docs/tutorials/docs/tutorials/ is wrong
- can you please update the URL as if we created another directory, i.e. guestbook/ under stateless-deployment/?
guestbook/README.md
Outdated
| - A [redis](http://redis.io/) master (for storage), and a replicated set of redis 'slaves'. | ||
| {% include task-tutorial-prereqs.md %} | ||
| Download the following configuration files: | ||
| 1. [redis-master-deployment.yaml](https://kubernetes.io/docs/tutorials/docs/tutorials/stateless-application/redis-master-deployment.yaml) |
There was a problem hiding this comment.
add a space below the 1. otherwise they all render on the same line (not as a list). also enumerating them as 1. 2. 3. is not important, you can just call them all 1. 1. 1., it will count the same.
markdown rule of thumb: when in doubt, add spaces.
guestbook/README.md
Outdated
|
|
||
| If you are in a live Kubernetes cluster, you can just kill the pods by deleting the Deployments and Services. Using labels to select the resources to delete is an easy way to do this in one command. | ||
| The guestbook application has a web frontend serving the HTTP requests written in PHP. It is configured to connect to the 'redis-master' Service for write requests and the 'redis-slave' service for Read requests. |
There was a problem hiding this comment.
instead of single-quotes, use backtick for <code> style for consistency.
guestbook/README.md
Outdated
|
|
||
| If the `LoadBalancer` specification is used, it can take a short period for an external IP to show up in `kubectl get services` output, but you should then see it listed as well, e.g. like this: | ||
| **Note:** Some cloud providers, like Google Compute Engine or Google Container Engine, support external load balancers. If your cloud provider supports load balancers and you want to use it, simply delete or comment out `type: NodePort`, and uncomment `type: LoadBalancer`. | ||
| {: note} |
There was a problem hiding this comment.
missing period in .note. callout doesn't render.
guestbook/README.md
Outdated
|
|
||
| You can list the forwarding rules like this (the forwarding rule also indicates the external IP): | ||
| Once the frontend Service is running, you need to find the IP address to view your Guestbook. |
There was a problem hiding this comment.
Add something like:
If you deployed this application to Minikube or a local cluster ...
guestbook/README.md
Outdated
| [gce-firewall-docs]: https://cloud.google.com/compute/docs/networking#firewalls | ||
| ### Viewing the Frontend Service via `LoadBalancer` | ||
|
|
||
| Once the frontend Service is running, you need to find the IP address to view your Guestbook. |
There was a problem hiding this comment.
Add something like:
If you deployed the
frontend-service.yamlmanifest withtype: LoadBalancerconfiguration...
guestbook/README.md
Outdated
|
|
||
| deployment "redis-master" deleted | ||
| deployment "redis-slave" deleted | ||
|
|
There was a problem hiding this comment.
you can delete these empty lines in the output, it looks more confusing IMO. Also there won't be empty lines in the output if I copypaste the commands above
guestbook/README.md
Outdated
| {% endcapture %} | ||
|
|
||
| {% capture whatsnext %} | ||
| * Read more about [connecting applications](https://kubernetes.io/docs/concepts/services-networking/connect-applications-service/) |
There was a problem hiding this comment.
Before this item, can you link to
- WordPress+MySQL tutorial
- Kubernetes Basics Interactive tutorial (/docs/tutorials/kubernetes-basics/)
|
/lgtm |
k8s-ci-robot
added
the
lgtm
No description provided.