Merge pull request #2725 from WillemMali/add-documentation-index

added documentation index
2017-06-16 10:18:56 -04:00 · 2017-06-16 10:18:56 -04:00 · de6d4e69f5
parent 4d0c12eb20 e69fdd3988
commit de6d4e69f5
5 changed files with 143 additions and 49 deletions
--- a/README.md
+++ b/README.md
@ -8,12 +8,14 @@

 The easiest way to get a production grade Kubernetes cluster up and running.

+
 ## What is kops?

 We like to think of it as `kubectl` for clusters.

 `kops` helps you create, destroy, upgrade and maintain production-grade, highly available, Kubernetes clusters from the command line.  AWS (Amazon Web Services) is currently officially supported, with GCE and VMware vSphere in alpha and other platforms planned.

+
 ## Can I see it in action?

 <p align="center">
@ -27,6 +29,7 @@ We like to think of it as `kubectl` for clusters.
 To replicate the above demo, check out our [tutorial](/docs/aws.md) for
 launching a Kubernetes cluster hosted on AWS.

+
 ## Features

 * Automates the provisioning of Kubernetes clusters in ([AWS](/docs/aws.md))
@ -38,14 +41,22 @@ launching a Kubernetes cluster hosted on AWS.
 * Command line [autocompletion](/docs/cli/kops_completion.md)
 * Community supported!

+
+## Documentations
+
+Documentation is in the `/docs` directory, [and the index is here.](docs/README.md)
+
+
 ## Installing

 `kubectl` is required, see [here](http://kubernetes.io/docs/user-guide/prereqs/).

+
 ### OSX From Homebrew (Latest Stable Release)

 ```console
 $ brew update && brew install kops
+
 ```
 ### Linux

@ -56,27 +67,15 @@ $ chmod +x kops-linux-amd64                 # Add execution permissions
 $ mv kops-linux-amd64 /usr/local/bin/kops   # Move the kops to /usr/local/bin
 ```

-### Developer From Source


-Go 1.8+ and make are required. You may need to do a full build including pushing protokube, nodeup, and kops to s3.
-
-See the [install notes](/docs/install.md) for more information.
-
-```console
-$ go get -d k8s.io/kops
-$ cd ${GOPATH}/src/k8s.io/kops/
-$ git checkout release
-$ make
-```
-
-At this time, Windows is not a supported platform.

 ## History

 See the [releases](https://github.com/kubernetes/kops/releases) for more
 information on changes between releases.

+
 ## Getting involved and contributing!

 Are you interested in contributing to kops? We, the maintainers and community, would love your suggestions, contributions, and help! We have a quick-start guide on [adding a feature](/docs/development/adding_a_feature.md).  Also, the maintainers can be contacted at any time to learn more about how to get involved.
@ -108,10 +107,12 @@ __Pull Requests__
 * [@geojaz](https://github.com/geojaz)
 * [@yissachar](https://github.com/yissachar)

+
 ## Office Hours

 Kops maintainers set aside one hour every other week for **public** office hours. Office hours are hosted on a [zoom video chat](https://zoom.us/my/k8ssigaws) on Fridays at [5 pm UTC/12 noon ET/9 am US Pacific](http://www.worldtimebuddy.com/?pl=1&lid=100,5,8,12), on odd week numbered weeks.  We strive to get to know and help developers either working on `kops` or interested in getting to know more about the project.

+
 ### Open Office Hours Topics

 Include but not limited to:
@ -136,19 +137,10 @@ date +%V

 The maintainers and other community members are generally available on the [kubernetes slack](https://github.com/kubernetes/community#slack-chat) in [#kops](https://kubernetes.slack.com/messages/kops/), so come find and chat with us about how kops can be better for you!

-## Other Resources
-
- - Create [kubecfg settings for kubectl](/docs/tips.md#create-kubecfg-settings-for-kubectl)
- - Set up [add-ons](/docs/addons.md), to add important functionality to Kubernetes
- - Learn about [InstanceGroups](/docs/instance_groups.md); change
- instance types, number of nodes, and other options
- - Read about [networking options](/docs/networking.md)
- - Look at our [other interesting modes](/docs/commands.md#other-interesting-modes)
- - Full command line interface [documentation](/docs/cli/kops.md)

 ## GitHub Issues

-#### Bugs
+### Bugs

 If you think you have found a bug please follow the instructions below.

@ -159,7 +151,8 @@ If you think you have found a bug please follow the instructions below.
 - Remember users might be searching for your issue in the future, so please give it a meaningful title to helps others.
 - Feel free to reach out to the kops community on [kubernetes slack](https://github.com/kubernetes/community#slack-chat)

-#### Features
+
+### Features

 We also use the issue tracker to track features. If you have an idea for a feature, or think you can help kops become even more awesome follow the steps below.

--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,93 @@
+Documentation Index
+===================
+
+Quick start
+-----------
+* [Getting started on AWS](aws.md)
+* [CLI reference](cli/kops.md)
+
+
+Overview
+--------
+
+* [Command-line interface](#commandline-interface)
+* [Inspection](#inspection)
+* [`kops` design documents](#kops-design-documents)
+* [Networking](#networking)
+* [Operations](#operations)
+* [Security](#security)
+* [Workflows](#workflows)
+
+
+
+### Command-line interface ###
+
+* [CLI argument explanations](arguments.md)
+* [CLI reference](cli/kops.md)
+* [Commands](commands.md)
+    * miscellaneous CLI-related remarks
+* [Experimental features](experimental.md)
+    * list of and how to enable experimental flags in the CLI
+* [kubectl](kubectl.md)
+    * how to point kubectl to your `kops` cluster
+
+
+### Inspection ###
+
+* [Download `kops` configuration](download_config.md)
+    * methods to download the current generated `kops` configuration
+* [Get AWS subdomain NS records](ns.md)
+
+
+### `kops` design documents ###
+
+* [`kops` cluster boot sequence](boot-sequence.md)
+* [`kops` cluster spec](cluster_spec.md)
+* [`kops` instance groups](instance_groups.md)
+* [`kops` philosophy](philosophy.md)
+* [`kops` state store](state.md)
+
+
+### Networking ###
+
+* [Networking overview](networking.md)
+* [Run `kops` in an existing VPC](run_in_existing_vpc.md)
+* [Supported network topologies](topology.md)
+* [Subdomain setup](creating_subdomain.md)
+
+
+### Operations ###
+
+* [Cluster addon manager](addon_manager.md)
+* [Cluster addons](addons.md)
+* [Cluster configuration management](changing_configuration.md)
+* [Cluster upgrades and migrations](cluster_upgrades_and_migrations.md)
+* [`etcd` volume encryption setup](etcd_volume_encryption.md)
+* [`etcd` backup setup](etcd_backup.md)
+* [GPU setup](gpu.md)
+* [High Availability](high_availability.md)
+* [InstanceGroup images](images.md)
+    * how to use other image for cluster nodes, and information on available/tested images
+* [`k8s` upgrading](upgrade.md)
+* [`kops` updating](update_kops.md)
+* [`kube-up` to `kops` upgrade](upgrade_from_kubeup.md)
+* [Label management](labels.md)
+    * for cluster nodes
+* [Secret management](secrets.md)
+* [Single-master to multi-master update](single-to-multi-master.md)
+
+
+### Security ###
+
+* [Bastion setup](bastion.md)
+* [IAM roles](iam_roles.md)
+* [MFA setup](mfa.md)
+    * how to set up MFA for `kops`
+* [Security](security.md)
+    * overview of secret storage, SSH credentials etc.
+
+
+### Workflows ###
+
+* [E2E testing with `kops` clusters](testing.md)
+* [Getting started on AWS](aws.md)
--- a/docs/advanced_create.md
+++ b/docs/advanced_create.md
@ -1,20 +0,0 @@
-# Advanced Example
-
-Example Create Cluster Command for HA / Private Topology
-
-```
-kops create cluster \
-    --node-count 3 \
-    --zones us-west-2a,us-west-2b,us-west-2c \
-    --master-zones us-west-2a,us-west-2b,us-west-2c \
-    --dns-zone example.com \
-    --node-size t2.medium \
-    --master-size t2.medium \
-    --node-security-groups sg-12345678 \
-    --master-security-groups sg-12345678,i-abcd1234 \
-    --topology private \
-    --networking weave \
-    --cloud-labels "Team=Dev,Owner=John Doe" \
-    --image 293135079892/k8s-1.4-debian-jessie-amd64-hvm-ebs-2016-11-16 \
-    ${NAME}
-```
--- a/docs/high_availability.md
+++ b/docs/high_availability.md
@ -1,6 +1,8 @@
-# High Availability (HA)
+High Availability (HA)
+======================

-## Introduction
+Introduction
+-------------

 Kubernetes has two strategies for high availability:

@ -27,7 +29,9 @@ In short:
 * A multi-node kops cluster can tolerate the outage of a single AZ
 * Federation will allow you to create "uber-clusters" that can tolerate a regional outage

-## Using Kops HA
+
+Using Kops HA
+-------------

 We can create HA clusters using kops, but only it's important to note that migrating from a single-master
 cluster to a multi-master cluster is a complicated operation (described [here](./single-to-multi-master.md)).
@ -58,3 +62,27 @@ As a result there are a few considerations that need to be taken into account wh
  If we create 2 (or more) masters in the same AZ, then failure of the AZ will likely cause etcd to lose quorum
  and stop operating (with 3 nodes).  Running in the same AZ therefore increases the risk of cluster disruption,
  though it can be a valid scenario, particularly if combined with [federation](https://kubernetes.io/docs/user-guide/federation/).
+
+
+Advanced Example
+----------------
+
+Another example `create cluster` invocation for HA with [a private network topology](topology.md):
+
+```
+kops create cluster \
+    --node-count 3 \
+    --zones us-west-2a,us-west-2b,us-west-2c \
+    --master-zones us-west-2a,us-west-2b,us-west-2c \
+    --dns-zone example.com \
+    --node-size t2.medium \
+    --master-size t2.medium \
+    --node-security-groups sg-12345678 \
+    --master-security-groups sg-12345678,i-abcd1234 \
+    --topology private \
+    --networking weave \
+    --cloud-labels "Team=Dev,Owner=John Doe" \
+    --image 293135079892/k8s-1.4-debian-jessie-amd64-hvm-ebs-2016-11-16 \
+    ${NAME}
+```
+
--- a/docs/kubectl.md
+++ b/docs/kubectl.md
@ -1,4 +1,4 @@
-# Tips and Tricks
+# kubectl

 ## Create kubecfg settings for kubectl

@ -16,4 +16,4 @@ ${GOPATH}/bin/kops export kubecfg ${NAME}

 You can now use kubernetes using the kubectl tool (after allowing a few minutes for the cluster to come up):

-```kubectl get nodes```
+```kubectl get nodes```