Ensure all docs and examples in user guide are reachable #11352

janetkuo · 2015-07-16T00:40:39Z

Also cross-link concept/feature docs, feature-oriented examples, and tutorials.

k8s-bot · 2015-07-16T01:13:12Z

GCE e2e build/test passed for commit d0c37c2c8a734e29071a64128e2e5958798bf592.

bgrant0607 · 2015-07-16T06:58:17Z

docs/user-guide/README.md

@@ -64,6 +64,9 @@ If you don't have much familiarity with Kubernetes, we recommend you read the fo
 [**Overview**](overview.md)
 : A brief overview of Kubernetes concepts.

+**Cluster**
+: A cluster is the compute resources on top of which your containers are built.


I intentionally omitted Cluster and Node here, on the theory that those concepts should be defined in the admin guide instead.

I see. I add this because I saw that Cluster was mentioned several times in some of the documents (such as Kubernetes 101) without explaining it. I think that is likely to confuse first-time users.

Fair enough.

I'd use a definition similar to that used by GKE: https://cloud.google.com/container-engine/docs/clusters/

A cluster is a set of physical or virtual machines and other infrastructure resources used by Kubernetes to run your applications.

I'd change the definition in the top-level README.md, also. We don't "build" containers, so that doesn't even make sense.

We should define node, as well, then.

A node is a physical or virtual machine running Kubernetes, onto which pods can be scheduled.

Both terms should link to docs. Node can link to ../admin/node.md. Cluster doesn't have a great doc, but maybe ../admin/README.md.

I'll modify the definition of Cluster and add Node definition in kubernetes/README.md too.

I'll add other concepts (volume, namespace, etc) in /README.md too.

We don't want to clutter /README.md much, so I wouldn't add more to it.

Well, adding Node is fine.

bgrant0607 · 2015-07-16T17:04:29Z

I expected more cross-linking. Did you ensure that every example in user-guide links to a corresponding doc and vice versa?

bgrant0607 · 2015-07-16T17:07:39Z

I don't think docs/user-guide/logging-demo links to docs/user-guide/logging.md, for instance.

bgrant0607 · 2015-07-16T17:08:30Z

docs/user-guide/README.md

@@ -107,6 +110,8 @@ If you don't have much familiarity with Kubernetes, we recommend you read the fo
  * [Downward API: accessing system configuration from a pod](downward-api.md)
  * [Images and registries](images.md)
  * [Migrating from docker-cli to kubectl](docker-cli-to-kubectl.md)
+  * [Assign a pod to a specific node](node-selection/)


Assign a pod to selected nodes

Assign pods to selected nodes

bgrant0607 · 2015-07-16T17:10:04Z

Please also link the update-demo back to docs/user-guide/managing-deployments.md#updating-your-application-without-a-service-outage

bgrant0607 · 2015-07-16T17:12:03Z

Somehow the link to secrets.md in docs/user-guide/secrets/README.md is broken. Please fix it.

janetkuo · 2015-07-16T17:18:56Z

I checked to ensure that all examples here are reference except for /logging-demo. I didn't include docs/user-guide/logging-demo because it only contains yaml files (pod specs) without further tutorial, and logging.md already contains a pod spec example and tutorial.

In this case, I'd add a link to /logging-demo in docs/user-guide/logging.md with explanation like "Try this link for more pod spec examples."

janetkuo · 2015-07-16T17:30:24Z

I tried the link to secrets.md in docs/user-guide/secrets/README.md and didn't see it broken. Could you try it again?

janetkuo · 2015-07-16T18:09:32Z

I'm checking the examples again to make sure every example in user-guide links to a corresponding doc and vice versa.

bgrant0607 · 2015-07-16T18:26:57Z

This line in secrets/README.md is the culprit:

You can learn more about secrets [Here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/secrets.md).

janetkuo · 2015-07-16T18:28:44Z

That link is removed in this code change.

bgrant0607 · 2015-07-16T18:29:16Z

Maybe fix those in a separate PR:

grep -r "GoogleCloudPlatform/kubernetes/blob/master/docs" docs examples
docs/user-guide/limitrange/README.md:For a detailed description of the Kubernetes resource model, see [Resources](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/resources.md)
docs/user-guide/logging-demo/Makefile:# Google Cloud Logging: https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/getting-started-guides/logging.md
docs/user-guide/logging-demo/Makefile:# With Elasticsearch and Kibana logging: https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/getting-started-guides/logging-elasticsearch.md
docs/user-guide/update-demo/README.md:[here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/kubectl_proxy.md).
docs/user-guide/downward-api/README.md:namespace using the [downward API](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/downward_api.md).
docs/user-guide/secrets/README.md:You can learn more about secrets [Here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/secrets.md).
docs/getting-started-guides/aws.md:An up-to-date documentation page for this tool is available here: [kubectl manual](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/kubectl.md)
docs/getting-started-guides/aws.md:For more information, please read [kubeconfig files](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/kubeconfig-file.md)
docs/admin/cluster-large.md:At v1.0, Kubernetes supports clusters up to 100 nodes with 30-50 pods per node and 1-2 container per pod (as defined in the [1.0 roadmap](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/roadmap.md#reliability-and-performance)).
docs/admin/high-availability.md:the simple [Docker based single node cluster instructions](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/getting-started-guides/docker.md),
examples/cassandra/README.md:You may also note that we are setting some Cassandra parameters (```MAX_HEAP_SIZE``` and ```HEAP_NEWSIZE```) and adding information about the [namespace](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/namespaces.md).  We also tell Kubernetes that the container exposes both the ```CQL``` and ```Thrift``` API ports.  Finally, we tell the cluster manager that we need 0.5 cpu (0.5 core).
examples/guestbook/README.md:The services in a Kubernetes cluster are discoverable inside other containers [via environment variables](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/services.md#environment-variables).
examples/guestbook/README.md:An alternative is to use the [cluster's DNS service](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/services.md#dns), if it has been enabled for the cluster.  This lets all pods do name resolution of services automatically, based on the service name.
examples/guestbook/README.md:More generally, Kubernetes supports two ways of exposing a service onto an external IP address: `NodePort`s and `LoadBalancer`s , as described [here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/services.md#external-services).
examples/k8petstore/README.md:In the mean time, because the public IP will be deprecated in Kubernetes v1, we provide other 2 scripts k8petstore-loadbalancer.sh and k8petstore-nodeport.sh. As the names suggest, they rely on LoadBalancer and NodePort respectively. More details can be found [here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/services.md#external-services). 
examples/k8petstore/k8petstore-loadbalancer.sh:#This script assumes the cloud provider is able to create a load balancer. If this not the case, you may want to check out other ways to make the frontend service accessible from outside (https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/services.md#external-services)

janetkuo · 2015-07-16T18:29:22Z

docs/user-guide/secrets/README.md

@@ -22,8 +22,7 @@ certainly want the docs that go with that version.</h1>
 <!-- END MUNGE: UNVERSIONED_WARNING -->
 # Secrets example

-Following this example, you will create a secret and a pod that consumes that secret in a volume.
-You can learn more about secrets [Here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/secrets.md).


link removed

Ah. Thanks.

janetkuo · 2015-07-16T18:38:09Z

Links will be changed to be relative links in #11385

bgrant0607 · 2015-07-16T18:43:17Z

Thanks

janetkuo · 2015-07-16T22:48:10Z

PTAL

bgrant0607 · 2015-07-16T22:48:23Z

README.md

-**Replication controllers** manage the lifecycle of pods. They ensure that a specified number of pods are running
-at any given time, by creating or killing pods as required. [More about replication controllers](docs/replication-controller.md).
+[**Pod**](docs/user-guide/pods.md)
+: Pods are a colocated group of Docker containers with shared volumes. They're the smallest deployable units that can be created, scheduled, and managed with Kubernetes. Pods can be created individually, but it's recommended that you use a replication controller even if creating a single pod.


s/Docker/application/

We also support Rocket.

bgrant0607 · 2015-07-16T22:52:43Z

Great! Thanks. Just a couple nits.

janetkuo · 2015-07-16T23:06:21Z

PTAL

bgrant0607 · 2015-07-16T23:17:59Z

LGTM!

k8s-bot · 2015-07-16T23:37:26Z

GCE e2e build/test passed for commit f9ac0c8fa59d7048bebdba16acc6ae70f02a5bad.

k8s-bot · 2015-07-17T00:07:59Z

GCE e2e build/test passed for commit b2467bef99f3ebe7c8638f56a48094d2a6abac1c.

bgrant0607 · 2015-07-17T05:51:41Z

Please rebase and re-run the doc mungers.

k8s-bot · 2015-07-17T06:08:51Z

GCE e2e build/test passed for commit b2467bef99f3ebe7c8638f56a48094d2a6abac1c.

k8s-bot · 2015-07-17T06:24:11Z

GCE e2e build/test passed for commit d3107c06fd81b1d95eee4c6a5ec9c67585041c7b.

k8s-bot · 2015-07-17T06:31:20Z

GCE e2e build/test passed for commit b0c68c4.

bgrant0607 · 2015-07-17T06:33:41Z

Thanks

Ensure all docs and examples in user guide are reachable

googlebot added the cla: yes label Jul 16, 2015

bgrant0607 reviewed Jul 16, 2015
View reviewed changes

bgrant0607 self-assigned this Jul 16, 2015

bgrant0607 added this to the v1.0 milestone Jul 16, 2015

bgrant0607 reviewed Jul 16, 2015
View reviewed changes

janetkuo reviewed Jul 16, 2015
View reviewed changes

janetkuo force-pushed the docs-reachable branch from d0c37c2 to f9ac0c8 Compare July 16, 2015 22:45

bgrant0607 reviewed Jul 16, 2015
View reviewed changes

janetkuo force-pushed the docs-reachable branch from f9ac0c8 to b2467be Compare July 16, 2015 23:04

bgrant0607 added lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-merge labels Jul 16, 2015

bgrant0607 added the kind/documentation Categorizes issue or PR as related to documentation. label Jul 16, 2015

bgrant0607 closed this Jul 17, 2015

bgrant0607 reopened this Jul 17, 2015

janetkuo force-pushed the docs-reachable branch from b2467be to d3107c0 Compare July 17, 2015 06:05

Ensure all docs and examples in user guide are reachable

b0c68c4

janetkuo force-pushed the docs-reachable branch from d3107c0 to b0c68c4 Compare July 17, 2015 06:13

bgrant0607 added a commit that referenced this pull request Jul 17, 2015

Merge pull request #11352 from JanetKuo/docs-reachable

5f34630

Ensure all docs and examples in user guide are reachable

bgrant0607 merged commit 5f34630 into kubernetes:master Jul 17, 2015

mikedanese mentioned this pull request Jul 17, 2015

fix link on root README.md #11451

Merged

xingzhou pushed a commit to xingzhou/kubernetes that referenced this pull request Dec 15, 2016

Merge pull request kubernetes#11352 from JanetKuo/docs-reachable

9107d38

Ensure all docs and examples in user guide are reachable

Ensure all docs and examples in user guide are reachable #11352

Ensure all docs and examples in user guide are reachable #11352

Conversation

janetkuo commented Jul 16, 2015

k8s-bot commented Jul 16, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Jul 16, 2015

bgrant0607 commented Jul 16, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Jul 16, 2015

bgrant0607 commented Jul 16, 2015

janetkuo commented Jul 16, 2015

janetkuo commented Jul 16, 2015

janetkuo commented Jul 16, 2015

bgrant0607 commented Jul 16, 2015

janetkuo commented Jul 16, 2015

bgrant0607 commented Jul 16, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janetkuo commented Jul 16, 2015

bgrant0607 commented Jul 16, 2015

janetkuo commented Jul 16, 2015

Choose a reason for hiding this comment

bgrant0607 commented Jul 16, 2015

janetkuo commented Jul 16, 2015

bgrant0607 commented Jul 16, 2015

k8s-bot commented Jul 16, 2015

k8s-bot commented Jul 17, 2015

bgrant0607 commented Jul 17, 2015

k8s-bot commented Jul 17, 2015

k8s-bot commented Jul 17, 2015

k8s-bot commented Jul 17, 2015

bgrant0607 commented Jul 17, 2015