From 95e92ad5476d64e09cd1affeb80befeeb7cc2687 Mon Sep 17 00:00:00 2001 From: Jerzy Szczepkowski Date: Fri, 30 Sep 2016 11:06:51 +0200 Subject: [PATCH 01/15] Updated hpa config file to the latest API version. Updated hpa config file to the latest API version. --- .../horizontal-pod-autoscaling/hpa-php-apache.yaml | 9 ++++----- .../user-guide/horizontal-pod-autoscaling/walkthrough.md | 9 ++++----- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/horizontal-pod-autoscaling/hpa-php-apache.yaml b/docs/user-guide/horizontal-pod-autoscaling/hpa-php-apache.yaml index 72d402743d..7ccdcabafd 100644 --- a/docs/user-guide/horizontal-pod-autoscaling/hpa-php-apache.yaml +++ b/docs/user-guide/horizontal-pod-autoscaling/hpa-php-apache.yaml @@ -1,14 +1,13 @@ -apiVersion: extensions/v1beta1 +apiVersion: autoscaling/v1 kind: HorizontalPodAutoscaler metadata: name: php-apache namespace: default spec: - scaleRef: + scaleTargetRef: + apiVersion: extensions/v1beta1 kind: Deployment name: php-apache - subresource: scale minReplicas: 1 maxReplicas: 10 - cpuUtilization: - targetPercentage: 50 + targetCPUUtilizationPercentage: 50 diff --git a/docs/user-guide/horizontal-pod-autoscaling/walkthrough.md b/docs/user-guide/horizontal-pod-autoscaling/walkthrough.md index d445b854e4..0f288352a0 100644 --- a/docs/user-guide/horizontal-pod-autoscaling/walkthrough.md +++ b/docs/user-guide/horizontal-pod-autoscaling/walkthrough.md @@ -127,20 +127,19 @@ Here CPU utilization dropped to 0, and so HPA autoscaled the number of replicas Instead of using `kubectl autoscale` command we can use the [hpa-php-apache.yaml](/docs/user-guide/horizontal-pod-autoscaling/hpa-php-apache.yaml) file, which looks like this: ```yaml -apiVersion: extensions/v1beta1 +apiVersion: autoscaling/v1 kind: HorizontalPodAutoscaler metadata: name: php-apache namespace: default spec: - scaleRef: + scaleTargetRef: + apiVersion: extensions/v1beta1 kind: Deployment name: php-apache - subresource: scale minReplicas: 1 maxReplicas: 10 - cpuUtilization: - targetPercentage: 50 + targetCPUUtilizationPercentage: 50 ``` We will create the autoscaler by executing the following command: From e857d466cbea3a02a452179901cb1bbe8b0688b0 Mon Sep 17 00:00:00 2001 From: Anirudh Ramanathan Date: Wed, 5 Oct 2016 18:44:15 -0700 Subject: [PATCH 02/15] Add example for pod using emptyDir --- docs/user-guide/volumes.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/user-guide/volumes.md b/docs/user-guide/volumes.md index e33bd3e018..463a34aeae 100644 --- a/docs/user-guide/volumes.md +++ b/docs/user-guide/volumes.md @@ -108,6 +108,25 @@ While tmpfs is very fast, be aware that unlike disks, tmpfs is cleared on machine reboot and any files you write will count against your container's memory limit. +#### Example pod + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-pd +spec: + containers: + - image: gcr.io/google_containers/test-webserver + name: test-container + volumeMounts: + - mountPath: /cache + name: cache-volume + volumes: + - name: cache-volume + emptyDir: {} +``` + ### hostPath A `hostPath` volume mounts a file or directory from the host node's filesystem From 8d5a4c0838e4b15ed641b1722c0a3c99e2c59394 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Ole=C5=9B?= Date: Thu, 6 Oct 2016 12:00:39 +0200 Subject: [PATCH 03/15] Fix kubectl get documentation - fix list of valid resource types - fix showing template It was fainling with following error message: Liquid Warning: Liquid syntax error (line 68): [:dot, "."] is not a valid expression in "{{.status.phase}}" in docs/user-guide/kubectl/kubectl_get.md --- docs/user-guide/kubectl/kubectl_get.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/kubectl/kubectl_get.md b/docs/user-guide/kubectl/kubectl_get.md index 99f2c25802..9a6f7fc228 100644 --- a/docs/user-guide/kubectl/kubectl_get.md +++ b/docs/user-guide/kubectl/kubectl_get.md @@ -12,6 +12,7 @@ Display one or many resources Display one or many resources. Valid resource types include: + * clusters (valid only for federation apiservers) * componentstatuses (aka 'cs') * configmaps (aka 'cm') @@ -68,7 +69,9 @@ kubectl get -o json pod web-pod-13je7 kubectl get -f pod.yaml -o json # Return only the phase value of the specified pod. +{% raw %} kubectl get -o template pod/web-pod-13je7 --template={{.status.phase}} +{% endraw %} # List all replication controllers and services together in ps output format. kubectl get rc,services From cd709f29aa71ea32e2ece3d1412261bd5bb05c1f Mon Sep 17 00:00:00 2001 From: Pablo Guerrero Date: Fri, 7 Oct 2016 08:47:24 +0200 Subject: [PATCH 04/15] Minor corrections --- docs/user-guide/petset.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/petset.md b/docs/user-guide/petset.md index 6063062df6..c3a2085a97 100644 --- a/docs/user-guide/petset.md +++ b/docs/user-guide/petset.md @@ -17,7 +17,7 @@ Throughout this doc you will see a few terms that are sometimes used interchange * Persistent Volume Claim (PVC): A request for storage, typically a [persistent volume](/docs/user-guide/persistent-volumes/walkthrough/). * Host name: The hostname attached to the UTS namespace of the pod, i.e the output of `hostname` in the pod. * DNS/Domain name: A *cluster local* domain name resolvable using standard methods (eg: [gethostbyname](http://linux.die.net/man/3/gethostbyname)). -* Ordinality: the proprety of being "ordinal", or occupying a position in a sequence. +* Ordinality: the property of being "ordinal", or occupying a position in a sequence. * Pet: a single member of a PetSet; more generally, a stateful application. * Peer: a process running a server, capable of communicating with other such processes. @@ -29,7 +29,7 @@ This doc assumes familiarity with the following Kubernetes concepts: * [Cluster DNS](/docs/admin/dns/) * [Headless Services](/docs/user-guide/services/#headless-services) * [Persistent Volumes](/docs/user-guide/volumes/) -* [Dynamic volume provisioning](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) +* [Persistent Volume Provisioning](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) You need a working Kubernetes cluster at version >= 1.3, with a healthy DNS [cluster addon](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md) at version >= 15. You cannot use PetSet on a hosted Kubernetes provider that has disabled `alpha` resources. @@ -85,7 +85,7 @@ Before you start deploying applications as PetSets, there are a few limitations * PetSet is an *alpha* resource, not available in any Kubernetes release prior to 1.3. * As with all alpha/beta resources, it can be disabled through the `--runtime-config` option passed to the apiserver, and in fact most likely will be disabled on hosted offerings of Kubernetes. * The only updatable field on a PetSet is `replicas` -* The storage for a given pet must either be provisioned by a [dynamic storage provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. Note that dynamic volume provisioning is also currently in alpha. +* The storage for a given pet must either be provisioned by a [persistent volume provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. Note that persistent volume provisioning is also currently in alpha. * Deleting and/or scaling a PetSet down will *not* delete the volumes associated with the PetSet. This is done to ensure safety first, your data is more valuable than an auto purge of all related PetSet resources. **Deleting the Persistent Volume Claims will result in a deletion of the associated volumes**. * All PetSets currently require a "governing service", or a Service responsible for the network identity of the pets. The user is responsible for this Service. * Updating an existing PetSet is currently a manual process, meaning you either need to deploy a new PetSet with the new image version, or orphan Pets one by one, update their image, and join them back to the cluster. @@ -392,7 +392,8 @@ $ grace=$(kubectl get po web-0 --template '{{.spec.terminationGracePeriodSeconds $ kubectl delete petset,po -l app=nginx $ sleep $grace $ kubectl delete pvc -l app=nginx -{% endraw %}``` +{% endraw %} +``` ## Troubleshooting From 30af17a161097f0b3a8991248306f22444850598 Mon Sep 17 00:00:00 2001 From: kcluster Date: Thu, 6 Oct 2016 20:19:34 +1100 Subject: [PATCH 05/15] Add link to KCluster.io --- docs/getting-started-guides/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/getting-started-guides/index.md b/docs/getting-started-guides/index.md index ac02bd726a..a728980e50 100644 --- a/docs/getting-started-guides/index.md +++ b/docs/getting-started-guides/index.md @@ -41,6 +41,8 @@ clusters. [AppsCode.com](https://appscode.com/products/cloud-deployment/) provides managed Kubernetes clusters for various public clouds (including AWS and Google Cloud Platform). +[KCluster.io](https://kcluster.io) provides highly available and scalable managed Kubernetes clusters for AWS. + ### Turn-key Cloud Solutions These solutions allow you to create Kubernetes clusters on a range of Cloud IaaS providers with only a @@ -120,6 +122,7 @@ IaaS Provider | Config. Mgmt | OS | Networking | Docs GKE | | | GCE | [docs](https://cloud.google.com/container-engine) | ['œ“][3] | Commercial Stackpoint.io | | multi-support | multi-support | [docs](http://www.stackpointcloud.com) | | Commercial AppsCode.com | Saltstack | Debian | multi-support | [docs](https://appscode.com/products/cloud-deployment/) | | Commercial +KCluster.io | | multi-support | multi-support | [docs](https://kcluster.io) | | Commercial GCE | Saltstack | Debian | GCE | [docs](/docs/getting-started-guides/gce) | ['œ“][1] | Project Azure | CoreOS | CoreOS | Weave | [docs](/docs/getting-started-guides/coreos/azure/) | | Community ([@errordeveloper](https://github.com/errordeveloper), [@squillace](https://github.com/squillace), [@chanezon](https://github.com/chanezon), [@crossorigin](https://github.com/crossorigin)) Azure | Ignition | Ubuntu | Azure | [docs](/docs/getting-started-guides/azure) | | Community (Microsoft: [@brendandburns](https://github.com/brendandburns), [@colemickens](https://github.com/colemickens)) From 252d8b8c41e0a07ae292450ce880a77416bc6daf Mon Sep 17 00:00:00 2001 From: Fede Diaz Date: Sun, 9 Oct 2016 17:46:04 +0200 Subject: [PATCH 06/15] Update centos_manual_config.md Added flannel configuration. Now more than one worker is available. Tested on Centos7 minimal install --- .../centos/centos_manual_config.md | 73 +++++++++++++++---- 1 file changed, 57 insertions(+), 16 deletions(-) diff --git a/docs/getting-started-guides/centos/centos_manual_config.md b/docs/getting-started-guides/centos/centos_manual_config.md index f794f485a4..40325c8985 100644 --- a/docs/getting-started-guides/centos/centos_manual_config.md +++ b/docs/getting-started-guides/centos/centos_manual_config.md @@ -10,15 +10,15 @@ assignees: ## Prerequisites -You need two machines with CentOS installed on them. +You need a machine acting as master and as many CentOS 7 hosts as you would like, that act as cluster nodes. ## Starting a cluster This is a getting started guide for CentOS. It is a manual configuration so you understand all the underlying packages / services / ports, etc... -This guide will only get ONE node working. Multiple nodes requires a functional [networking configuration](/docs/admin/networking) done outside of kubernetes. Although the additional Kubernetes configuration requirements should be obvious. +The Kubernetes package provides a few services: kube-apiserver, kube-scheduler, kube-controller-manager, kubelet, kube-proxy. These services are managed by systemd and the configuration resides in a central location: /etc/kubernetes. We will break the services up between the hosts. The first host, centos-master, will be the Kubernetes master. This host will run the kube-apiserver, kube-controller-manager and kube-scheduler. In addition, the master will also run _etcd_. The remaining hosts, centos-minion-n will be the nodes and run kubelet, proxy, cadvisor and docker. -The Kubernetes package provides a few services: kube-apiserver, kube-scheduler, kube-controller-manager, kubelet, kube-proxy. These services are managed by systemd and the configuration resides in a central location: /etc/kubernetes. We will break the services up between the hosts. The first host, centos-master, will be the Kubernetes master. This host will run the kube-apiserver, kube-controller-manager, and kube-scheduler. In addition, the master will also run _etcd_. The remaining host, centos-minion will be the node and run kubelet, proxy, cadvisor and docker. +All of then run flanneld as networking overlay. **System Information:** @@ -28,12 +28,14 @@ Please replace host IP with your environment. ```conf centos-master = 192.168.121.9 -centos-minion = 192.168.121.65 +centos-minion-1 = 192.168.121.65 +centos-minion-2 = 192.168.121.66 +centos-minion-3 = 192.168.121.67 ``` **Prepare the hosts:** -* Create a /etc/yum.repos.d/virt7-docker-common-release.repo on all hosts - centos-{master,minion} with following information. +* Create a /etc/yum.repos.d/virt7-docker-common-release.repo on all hosts - centos-{master,minion-n} with following information. ```conf [virt7-docker-common-release] @@ -42,17 +44,19 @@ baseurl=http://cbs.centos.org/repos/virt7-docker-common-release/x86_64/os/ gpgcheck=0 ``` -* Install Kubernetes and etcd on all hosts - centos-{master,minion}. This will also pull in docker and cadvisor. +* Install Kubernetes, etcd and flannel on all hosts - centos-{master,minion-n}. This will also pull in docker and cadvisor. ```shell -yum -y install --enablerepo=virt7-docker-common-release kubernetes etcd +yum -y install --enablerepo=virt7-docker-common-release kubernetes etcd flannel ``` * Add master and node to /etc/hosts on all machines (not needed if hostnames already in DNS) ```shell echo "192.168.121.9 centos-master -192.168.121.65 centos-minion" >> /etc/hosts +192.168.121.65 centos-minion-1 +192.168.121.66 centos-minion-2 +192.168.121.67 centos-minion-3" >> /etc/hosts ``` * Edit /etc/kubernetes/config which will be the same on all hosts to contain: @@ -74,7 +78,7 @@ KUBE_ALLOW_PRIV="--allow-privileged=false" KUBE_MASTER="--master=http://centos-master:8080" ``` -* Disable the firewall on both the master and node, as docker does not play well with other firewall rule managers +* Disable the firewall on the master and all the nodes, as docker does not play well with other firewall rule managers ```shell systemctl disable iptables-services firewalld @@ -114,17 +118,38 @@ KUBE_SERVICE_ADDRESSES="--service-cluster-ip-range=10.254.0.0/16" KUBE_API_ARGS="" ``` +* Configure ETCD to hold the network overlay configuration on master: + +```shell +$ etcdctl mkdir /kube-centos/network +$ etcdclt mk /kube-centos/network/config "{ \"Network\": \"172.40.0.0/16\", \"SubnetLen\": 24, \"Backend\": { \"Type\": \"vxlan\" } }" +``` + +* Configure flannel to overlay Docker network in /etc/sysconfig/flanneld on the master (also in the nodes as we'll see): + +```shell +# etcd url location. Point this to the server where etcd runs +FLANNEL_ETCD="http://centos-master:2379" + +# etcd config key. This is the configuration key that flannel queries +# For address range assignment +FLANNEL_ETCD_KEY="/kube-centos/network" + +# Any additional options that you want to pass +FLANNEL_OPTIONS="" +``` + * Start the appropriate services on master: ```shell -for SERVICES in etcd kube-apiserver kube-controller-manager kube-scheduler; do +for SERVICES in etcd kube-apiserver kube-controller-manager kube-scheduler flanneld; do systemctl restart $SERVICES systemctl enable $SERVICES systemctl status $SERVICES done ``` -**Configure the Kubernetes services on the node.** +**Configure the Kubernetes services on the nodes.** ***We need to configure the kubelet and start the kubelet and proxy*** @@ -138,7 +163,7 @@ KUBELET_ADDRESS="--address=0.0.0.0" KUBELET_PORT="--port=10250" # You may leave this blank to use the actual hostname -KUBELET_HOSTNAME="--hostname-override=centos-minion" +KUBELET_HOSTNAME="--hostname-override=centos-minion-n" # Check the node number! # Location of the api-server KUBELET_API_SERVER="--api-servers=http://centos-master:8080" @@ -147,10 +172,24 @@ KUBELET_API_SERVER="--api-servers=http://centos-master:8080" KUBELET_ARGS="" ``` -* Start the appropriate services on node (centos-minion). +* Configure flannel to overlay Docker network in /etc/sysconfig/flanneld (in all the nodes) ```shell -for SERVICES in kube-proxy kubelet docker; do +# etcd url location. Point this to the server where etcd runs +FLANNEL_ETCD="http://centos-master:2379" + +# etcd config key. This is the configuration key that flannel queries +# For address range assignment +FLANNEL_ETCD_KEY="/kube-centos/network" + +# Any additional options that you want to pass +FLANNEL_OPTIONS="" +``` + +* Start the appropriate services on node (centos-minion-n). + +```shell +for SERVICES in kube-proxy kubelet flanneld docker; do systemctl restart $SERVICES systemctl enable $SERVICES systemctl status $SERVICES @@ -164,7 +203,9 @@ done ```shell $ kubectl get nodes NAME LABELS STATUS -centos-minion Ready +centos-minion-1 Ready +centos-minion-2 Ready +centos-minion-3 Ready ``` **The cluster should be running! Launch a test pod.** @@ -176,7 +217,7 @@ You should have a functional cluster, check out [101](/docs/user-guide/walkthrou IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level -------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ---------------------------- -Bare-metal | custom | CentOS | _none_ | [docs](/docs/getting-started-guides/centos/centos_manual_config) | | Community ([@coolsvap](https://github.com/coolsvap)) +Bare-metal | custom | CentOS | flannel | [docs](/docs/getting-started-guides/centos/centos_manual_config) | | Community ([@coolsvap](https://github.com/coolsvap)) For support level information on all solutions, see the [Table of solutions](/docs/getting-started-guides/#table-of-solutions) chart. From f727a572b8d06aef9e15217b66acc564aba95702 Mon Sep 17 00:00:00 2001 From: Fede Diaz Date: Sun, 9 Oct 2016 17:52:25 +0200 Subject: [PATCH 07/15] Update centos_manual_config.md Warning about flannel network --- docs/getting-started-guides/centos/centos_manual_config.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting-started-guides/centos/centos_manual_config.md b/docs/getting-started-guides/centos/centos_manual_config.md index 40325c8985..1f1c3ff1dc 100644 --- a/docs/getting-started-guides/centos/centos_manual_config.md +++ b/docs/getting-started-guides/centos/centos_manual_config.md @@ -119,6 +119,7 @@ KUBE_API_ARGS="" ``` * Configure ETCD to hold the network overlay configuration on master: +**Warning** This network must be unused in your network infrastructure! `172.40.0.0/16` is free in our network. ```shell $ etcdctl mkdir /kube-centos/network From 93d5887c4b0e509849dc8602e6dfeac231a67d02 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Fri, 14 Oct 2016 17:45:21 -0700 Subject: [PATCH 08/15] Write new material about how to contribute to the Kubernetes docs. --- README.md | 81 ++------------- _config.yml | 3 + _data/support.yml | 6 ++ docs/contribute/create-pull-request.md | 94 ++++++++++++++++++ docs/contribute/page-templates.md | 2 +- .../contribute/stage-documentation-changes.md | 98 +++++++++++++++++++ docs/contribute/write-new-topic.md | 83 ++++++++++++++++ docs/index.md | 2 +- .../http-proxy-access-api.md | 90 ----------------- editdocs.md | 42 -------- 10 files changed, 295 insertions(+), 206 deletions(-) create mode 100644 docs/contribute/create-pull-request.md create mode 100644 docs/contribute/stage-documentation-changes.md create mode 100644 docs/contribute/write-new-topic.md delete mode 100644 docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md delete mode 100644 editdocs.md diff --git a/README.md b/README.md index a468c1f947..de5c7c2df3 100644 --- a/README.md +++ b/README.md @@ -4,66 +4,20 @@ Welcome! We are very pleased you want to contribute to the documentation and/or You can click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it. -## Staging the site on GitHub Pages +For more information about contributing to the Kubernetes documentation, see: -If you want to see your changes staged without having to install anything locally, remove the CNAME file in this directory and -change the name of the fork to be: +* [Creating a Documentation Pull Request](/docs/contribute/create-pull-request/) +* [Writing a New Topic](/docs/contribute/write-new-topic/) +* [Staging Your Documentation Changes](/docs/contribute/stage-documentation-changes/) +* [Using Page Templates](/docs/contribute/page-templates/) - YOUR_GITHUB_USERNAME.github.io +## Release Branch Staging -Then make your changes. +The Kubernetes site maintains staged versions at a subdomain provided by Netlify. Every PR for the Kubernetes site, either against the master branch or the upcoming release branch, is staged automatically. -When you visit [http://YOUR_GITHUB_USERNAME.github.io](http://YOUR_GITHUB_USERNAME.github.io) you should see a special-to-you version of the site that contains the changes you just made. - -## Staging the site locally (using Docker) - -Don't like installing stuff? Download and run a local staging server with a single `docker run` command. - - git clone https://github.com/kubernetes/kubernetes.github.io.git - cd kubernetes.github.io - docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0 - -Then visit [http://localhost:4000](http://localhost:4000) to see our site. Any changes you make on your local machine will be automatically staged. - -If you're interested you can view [the Dockerfile for this image](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile). - -## Staging the site locally (from scratch setup) - -The below commands to setup your environment for running GitHub pages locally. Then, any edits you make will be viewable -on a lightweight webserver that runs on your local machine. - -This will typically be the fastest way (by far) to iterate on docs changes and see them staged, once you get this set up, but it does involve several install steps that take awhile to complete, and makes system-wide modifications. - -Install Ruby 2.2 or higher. If you're on Linux, run these commands: - - apt-get install software-properties-common - apt-add-repository ppa:brightbox/ruby-ng - apt-get install ruby2.2 - apt-get install ruby2.2-dev - -* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/). -* If you're on a Windows machine you can use the [Ruby Installer](http://rubyinstaller.org/downloads/). During the installation make sure to check the option for *Add Ruby executables to your PATH*. - -The remainder of the steps should work the same across operating systems. - -To confirm you've installed Ruby correctly, at the command prompt run `gem --version` and you should get a response with your version number. Likewise you can confirm you have Git installed properly by running `git --version`, which will respond with your version of Git. - -Install the GitHub Pages package, which includes Jekyll: - - gem install github-pages - -Clone our site: - - git clone https://github.com/kubernetes/kubernetes.github.io.git - -Make any changes you want. Then, to see your changes locally: - - cd kubernetes.github.io - jekyll serve - -Your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000) -(or wherever Jekyll tells you). +The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/) +The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. ## GitHub help @@ -135,23 +89,6 @@ That, of course, will send users to: (Or whatever Kubernetes release that docs branch is associated with.) -## Branch structure - -The current version of the website is served out of the `master` branch. - -All versions of the site that relate to past and future versions will be named after their Kubernetes release number. For example, [the old branch for the 1.1 docs is called `release-1.1`](https://github.com/kubernetes/kubernetes.github.io/tree/release-1.1). - -Changes in the "docsv2" branch (where we are testing a revamp of the docs) are automatically staged here: -http://k8sdocs.github.io/docs/tutorials/ - -Changes in the "release-1.1" branch (for k8s v1.1 docs) are automatically staged here: -http://kubernetes-v1-1.github.io/ - -Changes in the "release-1.3" branch (for k8s v1.3 docs) are automatically staged here: -http://kubernetes-v1-3.github.io/ - -Editing of these branches will kick off a build using Travis CI that auto-updates these URLs; you can monitor the build progress at [https://travis-ci.org/kubernetes/kubernetes.github.io](https://travis-ci.org/kubernetes/kubernetes.github.io). - ## Config yaml guidelines Guidelines for config yamls that are included in the site docs. These diff --git a/_config.yml b/_config.yml index 5094499bfe..4c398d8d57 100644 --- a/_config.yml +++ b/_config.yml @@ -27,3 +27,6 @@ defaults: showedit: true permalink: pretty + +gems: + - jekyll-redirect-from diff --git a/_data/support.yml b/_data/support.yml index d287f0ecaa..e280c827d7 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -6,6 +6,12 @@ toc: - title: Contributing to the Kubernetes Docs section: + - title: Creating a Documentation Pull Request + path: /docs/contribute/create-pull-request/ + - title: Writing a New Topic + path: /docs/contribute/write-new-topic/ + - title: Staging Your Documentation Changes + path: /docs/contribute/stage-documentation-changes/ - title: Using Page Templates path: /docs/contribute/page-templates/ diff --git a/docs/contribute/create-pull-request.md b/docs/contribute/create-pull-request.md new file mode 100644 index 0000000000..833b4abf08 --- /dev/null +++ b/docs/contribute/create-pull-request.md @@ -0,0 +1,94 @@ +--- +redirect_from: + - /editdocs/ +--- + +{% capture overview %} + +To contribute to the Kubernetes documentation, create a pull request against the +[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} +repository. This page shows how to create a pull request. + +{% endcapture %} + +{% capture prerequisites %} + +1. Create a [GitHub account](https://github.com){: target="_blank"}. + +1. Sign the +[Google Contributor License Agreement](https://cla.developers.google.com/about/google-individual){: target="_blank"}. + +1. Sign the +[Linux Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}. + +{% endcapture %} + +{% capture steps %} + +### Creating a fork of the Kubernetes documentation repository + +1. Go to the +[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} +repository. + +1. In the upper-right corner, click **Fork**. This creates a copy of the +Kubernetes documentation repository in your GitHub account. The copy +is called a *fork*. + +### Making your changes + +1. In your GitHub account, in your fork of the Kubernetes docs, create +a new branch to use for your contribution. + +1. In your new branch, make your changes and commit them. If you want to +[write a new topic](/docs/contribute/write-new-topic/), +choose the +[page type](/docs/contribute/page-templates/) +that is the best fit for your content. + +### Submitting a pull request to the master branch + +If you want your change to be published in the released version Kubernetes docs, +create a pull request against the master branch of the Kubernetes +documentation repository. + +1. In your GitHub account, in your new branch, create a pull request +against the master branch of the kubernetes/kubernetes.github.io +repository. This opens a page that shows the status of your pull request. + +1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete. +To the right of **deploy/netlify**, click **Details**. This opens a staging +site where you can verify that your changes have rendered correctly. + +1. During the next few days, check your pull request for reviewer comments. +If needed, revise your pull request by committing changes to your +new branch in your fork. + +### Submitting a pull request to the <vnext> branch + +If your documentation change should not be released until the next release of +the Kubernetes product, create a pull request against the <vnext> branch +of the Kubernetes documentation repository. The <vnext> branch has the +form `release-`, for example release-1.5. + +1. In your GitHub account, in your new branch, create a pull request +against the <vnext> branch of the kubernetes/kubernetes.github.io +repository. This opens a page that shows the status of your pull request. + +1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete. +To the right of **deploy/netlify**, click **Details**. This opens a staging +site where you can verify that your changes have rendered correctly. + +1. During the next few days, check your pull request for reviewer comments. +If needed, revise your pull request by committing changes to your +new branch in your fork. + +{% endcapture %} + +{% capture whatsnext %} +* Learn about [writing a new topic](/docs/contribute/write-new-topic). +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [staging your changes](/docs/contribute/stage-documentation-changes). +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/contribute/page-templates.md b/docs/contribute/page-templates.md index da77bfc38e..62c4039d6a 100644 --- a/docs/contribute/page-templates.md +++ b/docs/contribute/page-templates.md @@ -71,7 +71,7 @@ Here's an interesting thing to know about the steps you just did.

Here's an example of a published topic that uses the task template:

-

Using an HTTP Proxy to Access Applications in a Cluster

+

Using an HTTP Proxy to Access the Kubernetes API

Tutorial template

diff --git a/docs/contribute/stage-documentation-changes.md b/docs/contribute/stage-documentation-changes.md new file mode 100644 index 0000000000..8c01d92158 --- /dev/null +++ b/docs/contribute/stage-documentation-changes.md @@ -0,0 +1,98 @@ +--- +--- + +{% capture overview %} +This page shows how to stage content that you want to contribute +to the Kubernetes documentation. +{% endcapture %} + +{% capture prerequisites %} +Create a fork of the Kubernetes documentation repository as described in +[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% capture steps %} + +### Staging from your GitHub account + +GitHub provides staging of content in your master branch. Note that you +might not want to merge your changes into your master branch. If that is +the case, choose another option for staging your content. + +1. In your GitHub account, in your fork, merge your changes into +the master branch. + +1. Change the name of your repository to `.github.io`, where +`` is the username of your GitHub account. + +1. Delete the `CNAME` file. + +1. View your staged content at this URL: + + https://.github.io + +### Staging a pull request + +When you create pull request against the Kubernetes documentation +repository, you can see your changes on a staging server. + +1. In your GitHub account, in your new branch, submit a pull request to the +kubernetes/kubernetes.github.io repository. This opens a page that shows the +status of your pull request. + +1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete. +To the right of **deploy/netlify**, click **Details**. This opens a staging +site where you see your changes. + +### Staging locally using Docker + +You can use the k8sdocs Docker image to run a local staging server. If you're +interested, you can view the +[Dockerfile](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile){: target="_blank"} +for this image. + +1. Install Docker if you don't already have it. + +1. Clone your fork to your local development machine. + +1. In the root of your cloned repository, enter this command to start a local +web server: + + docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0 + +1. View your staged content at +[http://localhost:4000](http://localhost:4000){: target="_blank"}. + +### Staging locally without Docker + +1. [Install Ruby 2.2 or later](https://www.ruby-lang.org){: target="_blank"}. + +1. [Install RubyGems](https://rubygems.org){: target="_blank"}. + +1. Verify that Ruby and RubyGems are installed: + + gem --version + +1. Install the GitHub Pages package, which includes Jekyll: + + gem install github-pages + +1. Clone your fork to your local development machine. + +1. In the root of your cloned repository, enter this command to start a local +web server: + + jekyll serve + +1. View your staged content at +[http://localhost:4000](http://localhost:4000){: target="_blank"}. + +{% endcapture %} + +{% capture whatsnext %} +* Learn about [writing a new topic](/docs/contribute/write-new-topic/). +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [creating a pull request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/contribute/write-new-topic.md b/docs/contribute/write-new-topic.md new file mode 100644 index 0000000000..c34f3cfde1 --- /dev/null +++ b/docs/contribute/write-new-topic.md @@ -0,0 +1,83 @@ +--- +--- + +{% capture overview %} +This page shows how to create a new topic for the Kubernetes docs. +{% endcapture %} + +{% capture prerequisites %} +Create a fork of the Kubernetes documentation repository as described in +[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% capture steps %} + +### Choosing a page type + +As you prepare to write a new topic, think about which of these page types +is the best fit for your content: + + + + + + + + + + + + + + + + + + +
TaskA task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge.
TutorialA tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial page has several sections, each of which has a sequence of steps. For example, a tutorial might provide a walkthrough of a code sample that illustrates a certain feature of Kubernetes. Tutorials can include surface-level explanations, but should link to related concept topics for deep explanations.
ConceptA concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials.
+ +Each page type has a +[template](/docs/contribute/page-templates/) +that you can use as you write your topic. +Using templates helps ensure consistency among topics of a given type. + +### Choosing a title and filename + +Choose a title that has the keywords you want search engines to find. +Create a filename that uses the words in your title separated by hyphens. +For example, the topic with title +[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) +has filename `http-proxy-access-api.md`. You don't need to put +"kubernetes" in the filename, because "kubernetes" is already in the +URL for the topic, for example: + + http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/ + +### Choosing a directory + +Depending on your page type, put your new file in a subdirectory of one of these: + +* /docs/tasks/ +* /docs/tutorials/ +* /docs/concepts/ + +You can put your file in an existing subdirectory, or you can create a new +subdirectory. + +### Creating an entry in the table of contents + +Depending page type, create an entry in one of these files: + +* /_data/tasks.yaml +* /_data/tutorials.yaml +* /_data/concepts.yaml + +{% endcapture %} + +{% capture whatsnext %} +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [staging your changes](/docs/contribute/stage-documentation-changes). +* Learn about [creating a pull request](/docs/contribute/write-new-topic). +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/index.md b/docs/index.md index 5e29c42dcb..9499ae68a2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -117,7 +117,7 @@ h2, h3, h4 {

Contribute to Our Docs

The docs for Kubernetes are open-source, just like the code for Kubernetes itself. The docs are on GitHub Pages, so you can fork it and it will auto-stage on username.github.io, previewing your changes!

- Write Docs for K8s + Write Docs for K8s

Need Help?

diff --git a/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md b/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md deleted file mode 100644 index 0c7ad2ca87..0000000000 --- a/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md +++ /dev/null @@ -1,90 +0,0 @@ ---- ---- - -{% capture overview %} -This page shows how to use an HTTP proxy to access the Kubernetes API. -{% endcapture %} - -{% capture prerequisites %} - -* Install [kubectl](http://kubernetes.io/docs/user-guide/prereqs). - -* Create a Kubernetes cluster, including a running Kubernetes - API server. One way to create a new cluster is to use - [Minikube](/docs/getting-started-guides/minikube). - -* Configure `kubectl` to communicate with your Kubernetes API server. This - configuration is done automatically if you use Minikube. - -* If you do not already have an application running in your cluster, start - a Hello world application by entering this command: - - kubectl run --image=gcr.io/google-samples/node-hello:1.0 --port=8080 - -{% endcapture %} - -{% capture steps %} - -### Using kubectl to start a proxy server - -This command starts a proxy to the Kubernetes API server: - - kubectl proxy --port=8080 - -### Exploring the Kubernetes API - -When the proxy server is running, you can explore the API using `curl`, `wget`, -or a browser. - -Get the API versions: - - curl http://localhost:8080/api/ - - { - "kind": "APIVersions", - "versions": [ - "v1" - ], - "serverAddressByClientCIDRs": [ - { - "clientCIDR": "0.0.0.0/0", - "serverAddress": "10.0.2.15:8443" - } - ] - } - -Get a list of pods: - - curl http://localhost:8080/api/v1/namespaces/default/pods - - { - "kind": "PodList", - "apiVersion": "v1", - "metadata": { - "selfLink": "/api/v1/namespaces/default/pods", - "resourceVersion": "33074" - }, - "items": [ - { - "metadata": { - "name": "kubernetes-bootcamp-2321272333-ix8pt", - "generateName": "kubernetes-bootcamp-2321272333-", - "namespace": "default", - "selfLink": "/api/v1/namespaces/default/pods/kubernetes-bootcamp-2321272333-ix8pt", - "uid": "ba21457c-6b1d-11e6-85f7-1ef9f1dab92b", - "resourceVersion": "33003", - "creationTimestamp": "2016-08-25T23:43:30Z", - "labels": { - "pod-template-hash": "2321272333", - "run": "kubernetes-bootcamp" - }, - ... - } - -{% endcapture %} - -{% capture whatsnext %} -Learn more about [kubectl proxy](/docs/user-guide/kubectl/kubectl_proxy). -{% endcapture %} - -{% include templates/task.md %} diff --git a/editdocs.md b/editdocs.md deleted file mode 100644 index 0291912aca..0000000000 --- a/editdocs.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -layout: docwithnav ---- - - -

 

- -
- -

Continue your edit

- -

Click the below link to edit the page you were just on. When you are done, press "Commit Changes" at the bottom of the screen. This will create a copy of our site on your GitHub account called a "fork." You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click "New Pull Request" to let us know about it.

- -

- -
-
- -

Edit our site in the cloud

- -

Click the below button to visit the repo for our site. You can then click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.

- -

Browse this site's source code

- -
- - - -{% include_relative README.md %} From 74791339ec923803538b755abbbfea6f20b2c111 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Fri, 14 Oct 2016 17:45:21 -0700 Subject: [PATCH 09/15] Write new material about how to contribute to the Kubernetes docs. --- README.md | 81 ++------------- _config.yml | 3 + _data/support.yml | 6 ++ docs/contribute/create-pull-request.md | 94 ++++++++++++++++++ docs/contribute/page-templates.md | 2 +- .../contribute/stage-documentation-changes.md | 98 +++++++++++++++++++ docs/contribute/write-new-topic.md | 83 ++++++++++++++++ docs/index.md | 2 +- .../http-proxy-access-api.md | 90 ----------------- editdocs.md | 42 -------- 10 files changed, 295 insertions(+), 206 deletions(-) create mode 100644 docs/contribute/create-pull-request.md create mode 100644 docs/contribute/stage-documentation-changes.md create mode 100644 docs/contribute/write-new-topic.md delete mode 100644 docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md delete mode 100644 editdocs.md diff --git a/README.md b/README.md index a468c1f947..85111edba9 100644 --- a/README.md +++ b/README.md @@ -4,66 +4,20 @@ Welcome! We are very pleased you want to contribute to the documentation and/or You can click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it. -## Staging the site on GitHub Pages +For more information about contributing to the Kubernetes documentation, see: -If you want to see your changes staged without having to install anything locally, remove the CNAME file in this directory and -change the name of the fork to be: +* [Creating a Documentation Pull Request](http://kubernetes.io/docs/contribute/create-pull-request/) +* [Writing a New Topic](http://kubernetes.io/docs/contribute/write-new-topic/) +* [Staging Your Documentation Changes](http://kubernetes.io/docs/contribute/stage-documentation-changes/) +* [Using Page Templates](http://kubernetes.io/docs/contribute/page-templates/) - YOUR_GITHUB_USERNAME.github.io +## Release Branch Staging -Then make your changes. +The Kubernetes site maintains staged versions at a subdomain provided by Netlify. Every PR for the Kubernetes site, either against the master branch or the upcoming release branch, is staged automatically. -When you visit [http://YOUR_GITHUB_USERNAME.github.io](http://YOUR_GITHUB_USERNAME.github.io) you should see a special-to-you version of the site that contains the changes you just made. - -## Staging the site locally (using Docker) - -Don't like installing stuff? Download and run a local staging server with a single `docker run` command. - - git clone https://github.com/kubernetes/kubernetes.github.io.git - cd kubernetes.github.io - docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0 - -Then visit [http://localhost:4000](http://localhost:4000) to see our site. Any changes you make on your local machine will be automatically staged. - -If you're interested you can view [the Dockerfile for this image](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile). - -## Staging the site locally (from scratch setup) - -The below commands to setup your environment for running GitHub pages locally. Then, any edits you make will be viewable -on a lightweight webserver that runs on your local machine. - -This will typically be the fastest way (by far) to iterate on docs changes and see them staged, once you get this set up, but it does involve several install steps that take awhile to complete, and makes system-wide modifications. - -Install Ruby 2.2 or higher. If you're on Linux, run these commands: - - apt-get install software-properties-common - apt-add-repository ppa:brightbox/ruby-ng - apt-get install ruby2.2 - apt-get install ruby2.2-dev - -* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/). -* If you're on a Windows machine you can use the [Ruby Installer](http://rubyinstaller.org/downloads/). During the installation make sure to check the option for *Add Ruby executables to your PATH*. - -The remainder of the steps should work the same across operating systems. - -To confirm you've installed Ruby correctly, at the command prompt run `gem --version` and you should get a response with your version number. Likewise you can confirm you have Git installed properly by running `git --version`, which will respond with your version of Git. - -Install the GitHub Pages package, which includes Jekyll: - - gem install github-pages - -Clone our site: - - git clone https://github.com/kubernetes/kubernetes.github.io.git - -Make any changes you want. Then, to see your changes locally: - - cd kubernetes.github.io - jekyll serve - -Your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000) -(or wherever Jekyll tells you). +The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/) +The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. ## GitHub help @@ -135,23 +89,6 @@ That, of course, will send users to: (Or whatever Kubernetes release that docs branch is associated with.) -## Branch structure - -The current version of the website is served out of the `master` branch. - -All versions of the site that relate to past and future versions will be named after their Kubernetes release number. For example, [the old branch for the 1.1 docs is called `release-1.1`](https://github.com/kubernetes/kubernetes.github.io/tree/release-1.1). - -Changes in the "docsv2" branch (where we are testing a revamp of the docs) are automatically staged here: -http://k8sdocs.github.io/docs/tutorials/ - -Changes in the "release-1.1" branch (for k8s v1.1 docs) are automatically staged here: -http://kubernetes-v1-1.github.io/ - -Changes in the "release-1.3" branch (for k8s v1.3 docs) are automatically staged here: -http://kubernetes-v1-3.github.io/ - -Editing of these branches will kick off a build using Travis CI that auto-updates these URLs; you can monitor the build progress at [https://travis-ci.org/kubernetes/kubernetes.github.io](https://travis-ci.org/kubernetes/kubernetes.github.io). - ## Config yaml guidelines Guidelines for config yamls that are included in the site docs. These diff --git a/_config.yml b/_config.yml index 5094499bfe..4c398d8d57 100644 --- a/_config.yml +++ b/_config.yml @@ -27,3 +27,6 @@ defaults: showedit: true permalink: pretty + +gems: + - jekyll-redirect-from diff --git a/_data/support.yml b/_data/support.yml index d287f0ecaa..e280c827d7 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -6,6 +6,12 @@ toc: - title: Contributing to the Kubernetes Docs section: + - title: Creating a Documentation Pull Request + path: /docs/contribute/create-pull-request/ + - title: Writing a New Topic + path: /docs/contribute/write-new-topic/ + - title: Staging Your Documentation Changes + path: /docs/contribute/stage-documentation-changes/ - title: Using Page Templates path: /docs/contribute/page-templates/ diff --git a/docs/contribute/create-pull-request.md b/docs/contribute/create-pull-request.md new file mode 100644 index 0000000000..833b4abf08 --- /dev/null +++ b/docs/contribute/create-pull-request.md @@ -0,0 +1,94 @@ +--- +redirect_from: + - /editdocs/ +--- + +{% capture overview %} + +To contribute to the Kubernetes documentation, create a pull request against the +[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} +repository. This page shows how to create a pull request. + +{% endcapture %} + +{% capture prerequisites %} + +1. Create a [GitHub account](https://github.com){: target="_blank"}. + +1. Sign the +[Google Contributor License Agreement](https://cla.developers.google.com/about/google-individual){: target="_blank"}. + +1. Sign the +[Linux Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}. + +{% endcapture %} + +{% capture steps %} + +### Creating a fork of the Kubernetes documentation repository + +1. Go to the +[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} +repository. + +1. In the upper-right corner, click **Fork**. This creates a copy of the +Kubernetes documentation repository in your GitHub account. The copy +is called a *fork*. + +### Making your changes + +1. In your GitHub account, in your fork of the Kubernetes docs, create +a new branch to use for your contribution. + +1. In your new branch, make your changes and commit them. If you want to +[write a new topic](/docs/contribute/write-new-topic/), +choose the +[page type](/docs/contribute/page-templates/) +that is the best fit for your content. + +### Submitting a pull request to the master branch + +If you want your change to be published in the released version Kubernetes docs, +create a pull request against the master branch of the Kubernetes +documentation repository. + +1. In your GitHub account, in your new branch, create a pull request +against the master branch of the kubernetes/kubernetes.github.io +repository. This opens a page that shows the status of your pull request. + +1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete. +To the right of **deploy/netlify**, click **Details**. This opens a staging +site where you can verify that your changes have rendered correctly. + +1. During the next few days, check your pull request for reviewer comments. +If needed, revise your pull request by committing changes to your +new branch in your fork. + +### Submitting a pull request to the <vnext> branch + +If your documentation change should not be released until the next release of +the Kubernetes product, create a pull request against the <vnext> branch +of the Kubernetes documentation repository. The <vnext> branch has the +form `release-`, for example release-1.5. + +1. In your GitHub account, in your new branch, create a pull request +against the <vnext> branch of the kubernetes/kubernetes.github.io +repository. This opens a page that shows the status of your pull request. + +1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete. +To the right of **deploy/netlify**, click **Details**. This opens a staging +site where you can verify that your changes have rendered correctly. + +1. During the next few days, check your pull request for reviewer comments. +If needed, revise your pull request by committing changes to your +new branch in your fork. + +{% endcapture %} + +{% capture whatsnext %} +* Learn about [writing a new topic](/docs/contribute/write-new-topic). +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [staging your changes](/docs/contribute/stage-documentation-changes). +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/contribute/page-templates.md b/docs/contribute/page-templates.md index da77bfc38e..62c4039d6a 100644 --- a/docs/contribute/page-templates.md +++ b/docs/contribute/page-templates.md @@ -71,7 +71,7 @@ Here's an interesting thing to know about the steps you just did.

Here's an example of a published topic that uses the task template:

-

Using an HTTP Proxy to Access Applications in a Cluster

+

Using an HTTP Proxy to Access the Kubernetes API

Tutorial template

diff --git a/docs/contribute/stage-documentation-changes.md b/docs/contribute/stage-documentation-changes.md new file mode 100644 index 0000000000..8c01d92158 --- /dev/null +++ b/docs/contribute/stage-documentation-changes.md @@ -0,0 +1,98 @@ +--- +--- + +{% capture overview %} +This page shows how to stage content that you want to contribute +to the Kubernetes documentation. +{% endcapture %} + +{% capture prerequisites %} +Create a fork of the Kubernetes documentation repository as described in +[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% capture steps %} + +### Staging from your GitHub account + +GitHub provides staging of content in your master branch. Note that you +might not want to merge your changes into your master branch. If that is +the case, choose another option for staging your content. + +1. In your GitHub account, in your fork, merge your changes into +the master branch. + +1. Change the name of your repository to `.github.io`, where +`` is the username of your GitHub account. + +1. Delete the `CNAME` file. + +1. View your staged content at this URL: + + https://.github.io + +### Staging a pull request + +When you create pull request against the Kubernetes documentation +repository, you can see your changes on a staging server. + +1. In your GitHub account, in your new branch, submit a pull request to the +kubernetes/kubernetes.github.io repository. This opens a page that shows the +status of your pull request. + +1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete. +To the right of **deploy/netlify**, click **Details**. This opens a staging +site where you see your changes. + +### Staging locally using Docker + +You can use the k8sdocs Docker image to run a local staging server. If you're +interested, you can view the +[Dockerfile](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile){: target="_blank"} +for this image. + +1. Install Docker if you don't already have it. + +1. Clone your fork to your local development machine. + +1. In the root of your cloned repository, enter this command to start a local +web server: + + docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0 + +1. View your staged content at +[http://localhost:4000](http://localhost:4000){: target="_blank"}. + +### Staging locally without Docker + +1. [Install Ruby 2.2 or later](https://www.ruby-lang.org){: target="_blank"}. + +1. [Install RubyGems](https://rubygems.org){: target="_blank"}. + +1. Verify that Ruby and RubyGems are installed: + + gem --version + +1. Install the GitHub Pages package, which includes Jekyll: + + gem install github-pages + +1. Clone your fork to your local development machine. + +1. In the root of your cloned repository, enter this command to start a local +web server: + + jekyll serve + +1. View your staged content at +[http://localhost:4000](http://localhost:4000){: target="_blank"}. + +{% endcapture %} + +{% capture whatsnext %} +* Learn about [writing a new topic](/docs/contribute/write-new-topic/). +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [creating a pull request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/contribute/write-new-topic.md b/docs/contribute/write-new-topic.md new file mode 100644 index 0000000000..c34f3cfde1 --- /dev/null +++ b/docs/contribute/write-new-topic.md @@ -0,0 +1,83 @@ +--- +--- + +{% capture overview %} +This page shows how to create a new topic for the Kubernetes docs. +{% endcapture %} + +{% capture prerequisites %} +Create a fork of the Kubernetes documentation repository as described in +[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% capture steps %} + +### Choosing a page type + +As you prepare to write a new topic, think about which of these page types +is the best fit for your content: + + + + + + + + + + + + + + + + + + +
TaskA task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge.
TutorialA tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial page has several sections, each of which has a sequence of steps. For example, a tutorial might provide a walkthrough of a code sample that illustrates a certain feature of Kubernetes. Tutorials can include surface-level explanations, but should link to related concept topics for deep explanations.
ConceptA concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials.
+ +Each page type has a +[template](/docs/contribute/page-templates/) +that you can use as you write your topic. +Using templates helps ensure consistency among topics of a given type. + +### Choosing a title and filename + +Choose a title that has the keywords you want search engines to find. +Create a filename that uses the words in your title separated by hyphens. +For example, the topic with title +[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) +has filename `http-proxy-access-api.md`. You don't need to put +"kubernetes" in the filename, because "kubernetes" is already in the +URL for the topic, for example: + + http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/ + +### Choosing a directory + +Depending on your page type, put your new file in a subdirectory of one of these: + +* /docs/tasks/ +* /docs/tutorials/ +* /docs/concepts/ + +You can put your file in an existing subdirectory, or you can create a new +subdirectory. + +### Creating an entry in the table of contents + +Depending page type, create an entry in one of these files: + +* /_data/tasks.yaml +* /_data/tutorials.yaml +* /_data/concepts.yaml + +{% endcapture %} + +{% capture whatsnext %} +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [staging your changes](/docs/contribute/stage-documentation-changes). +* Learn about [creating a pull request](/docs/contribute/write-new-topic). +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/index.md b/docs/index.md index 5e29c42dcb..9499ae68a2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -117,7 +117,7 @@ h2, h3, h4 {

Contribute to Our Docs

The docs for Kubernetes are open-source, just like the code for Kubernetes itself. The docs are on GitHub Pages, so you can fork it and it will auto-stage on username.github.io, previewing your changes!

- Write Docs for K8s + Write Docs for K8s

Need Help?

diff --git a/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md b/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md deleted file mode 100644 index 0c7ad2ca87..0000000000 --- a/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api.md +++ /dev/null @@ -1,90 +0,0 @@ ---- ---- - -{% capture overview %} -This page shows how to use an HTTP proxy to access the Kubernetes API. -{% endcapture %} - -{% capture prerequisites %} - -* Install [kubectl](http://kubernetes.io/docs/user-guide/prereqs). - -* Create a Kubernetes cluster, including a running Kubernetes - API server. One way to create a new cluster is to use - [Minikube](/docs/getting-started-guides/minikube). - -* Configure `kubectl` to communicate with your Kubernetes API server. This - configuration is done automatically if you use Minikube. - -* If you do not already have an application running in your cluster, start - a Hello world application by entering this command: - - kubectl run --image=gcr.io/google-samples/node-hello:1.0 --port=8080 - -{% endcapture %} - -{% capture steps %} - -### Using kubectl to start a proxy server - -This command starts a proxy to the Kubernetes API server: - - kubectl proxy --port=8080 - -### Exploring the Kubernetes API - -When the proxy server is running, you can explore the API using `curl`, `wget`, -or a browser. - -Get the API versions: - - curl http://localhost:8080/api/ - - { - "kind": "APIVersions", - "versions": [ - "v1" - ], - "serverAddressByClientCIDRs": [ - { - "clientCIDR": "0.0.0.0/0", - "serverAddress": "10.0.2.15:8443" - } - ] - } - -Get a list of pods: - - curl http://localhost:8080/api/v1/namespaces/default/pods - - { - "kind": "PodList", - "apiVersion": "v1", - "metadata": { - "selfLink": "/api/v1/namespaces/default/pods", - "resourceVersion": "33074" - }, - "items": [ - { - "metadata": { - "name": "kubernetes-bootcamp-2321272333-ix8pt", - "generateName": "kubernetes-bootcamp-2321272333-", - "namespace": "default", - "selfLink": "/api/v1/namespaces/default/pods/kubernetes-bootcamp-2321272333-ix8pt", - "uid": "ba21457c-6b1d-11e6-85f7-1ef9f1dab92b", - "resourceVersion": "33003", - "creationTimestamp": "2016-08-25T23:43:30Z", - "labels": { - "pod-template-hash": "2321272333", - "run": "kubernetes-bootcamp" - }, - ... - } - -{% endcapture %} - -{% capture whatsnext %} -Learn more about [kubectl proxy](/docs/user-guide/kubectl/kubectl_proxy). -{% endcapture %} - -{% include templates/task.md %} diff --git a/editdocs.md b/editdocs.md deleted file mode 100644 index 0291912aca..0000000000 --- a/editdocs.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -layout: docwithnav ---- - - -

 

- -
- -

Continue your edit

- -

Click the below link to edit the page you were just on. When you are done, press "Commit Changes" at the bottom of the screen. This will create a copy of our site on your GitHub account called a "fork." You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click "New Pull Request" to let us know about it.

- -

- -
-
- -

Edit our site in the cloud

- -

Click the below button to visit the repo for our site. You can then click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.

- -

Browse this site's source code

- -
- - - -{% include_relative README.md %} From 047974c924c4fbd6e762be1fbd05b11a770e3bd6 Mon Sep 17 00:00:00 2001 From: Chris Jones Date: Mon, 17 Oct 2016 15:13:44 -0600 Subject: [PATCH 10/15] Added more prequisites. --- docs/getting-started-guides/ubuntu.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting-started-guides/ubuntu.md b/docs/getting-started-guides/ubuntu.md index 56ef9d9515..e5a849d909 100644 --- a/docs/getting-started-guides/ubuntu.md +++ b/docs/getting-started-guides/ubuntu.md @@ -29,6 +29,7 @@ Internet to download the necessary files, while worker nodes do not. Ubuntu 15 which uses systemd instead of upstart. 4. Dependencies of this guide: etcd-2.2.1, flannel-0.5.5, k8s-1.2.0, may work with higher versions. 5. All the remote servers can be ssh logged in without a password by using key authentication. +6. The remote user on all machines is using /bin/bash as its login shell, and has sudo access. ## Starting a Cluster From 1480754235a31300b933887810443300d7bdeffd Mon Sep 17 00:00:00 2001 From: Feynman Liang Date: Mon, 17 Oct 2016 15:58:45 -0700 Subject: [PATCH 11/15] Correct typo in authorization header --- docs/admin/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index 5664e8b266..6819677107 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -101,7 +101,7 @@ quoting facilities of HTTP. For example: if the bearer token is header as shown below. ```http -Authentication: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269 +Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269 ``` ### Static Password File From 827ae558ec269a57a65186edd81efb27ee1c4a9d Mon Sep 17 00:00:00 2001 From: Fede Diaz Date: Tue, 18 Oct 2016 08:13:10 +0200 Subject: [PATCH 12/15] Update centos_manual_config.md Request change done. Fixed errata in flannel network. --- docs/getting-started-guides/centos/centos_manual_config.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting-started-guides/centos/centos_manual_config.md b/docs/getting-started-guides/centos/centos_manual_config.md index 1f1c3ff1dc..75b7cccbf7 100644 --- a/docs/getting-started-guides/centos/centos_manual_config.md +++ b/docs/getting-started-guides/centos/centos_manual_config.md @@ -10,7 +10,7 @@ assignees: ## Prerequisites -You need a machine acting as master and as many CentOS 7 hosts as you would like, that act as cluster nodes. +To configure Kubernetes with CentOS, you'll need a machine to act as a master, and one or more CentOS 7 hosts to act as cluster nodes. ## Starting a cluster @@ -119,11 +119,11 @@ KUBE_API_ARGS="" ``` * Configure ETCD to hold the network overlay configuration on master: -**Warning** This network must be unused in your network infrastructure! `172.40.0.0/16` is free in our network. +**Warning** This network must be unused in your network infrastructure! `172.30.0.0/16` is free in our network. ```shell $ etcdctl mkdir /kube-centos/network -$ etcdclt mk /kube-centos/network/config "{ \"Network\": \"172.40.0.0/16\", \"SubnetLen\": 24, \"Backend\": { \"Type\": \"vxlan\" } }" +$ etcdclt mk /kube-centos/network/config "{ \"Network\": \"172.30.0.0/16\", \"SubnetLen\": 24, \"Backend\": { \"Type\": \"vxlan\" } }" ``` * Configure flannel to overlay Docker network in /etc/sysconfig/flanneld on the master (also in the nodes as we'll see): From 65f244993cff22d76561f8cc9839e3bbdb803182 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Tue, 18 Oct 2016 09:50:31 -0700 Subject: [PATCH 13/15] Revise the section on Branch Structure and Staging. --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a4d5092fdf..40f2b42a32 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,20 @@ When you create a pull request (either against master or the upcoming release), - Look for "deploy/netlify"; you'll see "Deploy Preview Ready!" if staging was successful - Click "Details" to bring up the staged site and navigate to your changes -## Release Branch Staging +## Branch structure and staging -The Kubernetes site maintains staged versions at a subdomain provided by Netlify. Every PR for the Kubernetes site, either against the master branch or the upcoming release branch, is staged automatically. +The current version of the website is served out of the `master` branch. To make changes to the live docs, such as bug fixes, broken links, typos, etc, **target your pull request to the master branch** -The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/) +The `release-1.x` branch stores changes for **upcoming releases of Kubernetes**. For example, the `release-1.5` branch has changes for the 1.5 release. These changes target branches (and *not* master) to avoid publishing documentation updates prior to the release for which they're relevant. If you have a change for an upcoming release of Kubernetes, **target your pull request to the appropriate release branch**. -The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. +The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/). The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. + +When you create a pull request, either against the master branch or the upcoming release branch, your changes are staged automatically. +The Kubernetes site maintains staged versions at a subdomain provided by Netlify. ## Staging the site locally (using Docker) -Don't like installing stuff? Download and run a local staging server with a single `docker run` command. +Don't like installing stuff? Download and run a local staging server with a single `docker run` command. git clone https://github.com/kubernetes/kubernetes.github.io.git cd kubernetes.github.io @@ -62,7 +65,7 @@ Install Ruby 2.2 or higher. If you're on Linux, run these commands: apt-get install ruby2.2 apt-get install ruby2.2-dev -* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/). +* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/). * If you're on a Windows machine you can use the [Ruby Installer](http://rubyinstaller.org/downloads/). During the installation make sure to check the option for *Add Ruby executables to your PATH*. The remainder of the steps should work the same across operating systems. From ebbe5bbcc1a1a9331113a76c48fd39841349e3ea Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Tue, 18 Oct 2016 16:40:10 -0700 Subject: [PATCH 14/15] Additional updates to the Staging sections of the README. --- README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/README.md b/README.md index 40f2b42a32..c03defb3f7 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,6 @@ For more information about contributing to the Kubernetes documentation, see: * [Staging Your Documentation Changes](http://kubernetes.io/docs/contribute/stage-documentation-changes/) * [Using Page Templates](http://kubernetes.io/docs/contribute/page-templates/) -## Release Branch Staging - -The Kubernetes site maintains staged versions at a subdomain provided by Netlify. Every PR for the Kubernetes site, either against the master branch or the upcoming release branch, is staged automatically. - -The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/) - -The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. - ## Automatic Staging for Pull Requests When you create a pull request (either against master or the upcoming release), your changes are staged in a custom subdomain on Netlify so that you can see your changes in rendered form before the PR is merged. You can use this to verify that everything is correct before the PR gets merged. To view your changes: @@ -36,9 +28,6 @@ The `release-1.x` branch stores changes for **upcoming releases of Kubernetes**. The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/). The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. -When you create a pull request, either against the master branch or the upcoming release branch, your changes are staged automatically. -The Kubernetes site maintains staged versions at a subdomain provided by Netlify. - ## Staging the site locally (using Docker) Don't like installing stuff? Download and run a local staging server with a single `docker run` command. From e41f80c9a508d2c6f7f23e6ae42452fd65b0b906 Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Tue, 18 Oct 2016 17:25:48 -0700 Subject: [PATCH 15/15] Update README.md --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index c03defb3f7..381cd46567 100644 --- a/README.md +++ b/README.md @@ -77,11 +77,6 @@ Make any changes you want. Then, to see your changes locally: Your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000) (or wherever Jekyll tells you). -======= - -The staging site reflects the current state of what's been merged in the release branch, or in other words, what the docs will look like for the next upcoming release. It's automatically updated as new PRs get merged. - ->>>>>>> contribution-guide-2 ## GitHub help If you're a bit rusty with git/GitHub, you might want to read