From 85bcbe5a3865c043a4f739c9e92bac4f5a696102 Mon Sep 17 00:00:00 2001 From: Willem Mali Date: Wed, 14 Jun 2017 15:57:10 +0200 Subject: [PATCH 1/2] added documentation index I added a README.md in the /docs directory which should help make the docs more discoverable, and I added a reference to this index on the main README.md. I also renamed 'tips.md' to 'kubectl.md' and changed to title, to better reflect its content. --- README.md | 19 ++++++- docs/README.md | 97 ++++++++++++++++++++++++++++++++++++ docs/{tips.md => kubectl.md} | 4 +- 3 files changed, 117 insertions(+), 3 deletions(-) create mode 100644 docs/README.md rename docs/{tips.md => kubectl.md} (93%) diff --git a/README.md b/README.md index 6126c08ff6..f1adf28bc6 100644 --- 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?

@@ -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,8 +67,8 @@ $ 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 +### 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. @@ -72,11 +83,13 @@ $ 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 +121,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: @@ -146,6 +161,7 @@ The maintainers and other community members are generally available on the [kube - Look at our [other interesting modes](/docs/commands.md#other-interesting-modes) - Full command line interface [documentation](/docs/cli/kops.md) + ## GitHub Issues #### Bugs @@ -159,6 +175,7 @@ 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 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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..c6378b3ee7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,97 @@ +Documentation Index +=================== + +This page serves as a categorized index for all `kops` documentation. + + +Quick start +----------- +* [Getting started on AWS](aws.md) +* [CLI reference](cli/kops.md) + + +Overview +-------- + +* [CLI](#cli) +* [Introspection](#introspection) +* [`kops` design documents](#kops-design-documents) +* [Networking](#networking) +* [Operations](#operations) +* [Security](#security) +* [Workflows](#workflows) + + + +### CLI ### + +* [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 + + +### Introspection ### + +* [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 with HA creation example](advanced_create.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 modify IG images and information on available/tested images +* [Label management](labels.md) + * for AWS instance tags and `k8s` node labels +* [`kube-up` to `kops` migration](upgrade_from_kubeup.md) +* [Secret management](secrets.md) +* [Single-master to multi-master migration](single-to-multi-master.md) +* [`k8s` updating](upgrade.md) +* [`kops` updating](update_kops.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) diff --git a/docs/tips.md b/docs/kubectl.md similarity index 93% rename from docs/tips.md rename to docs/kubectl.md index f372870fba..491f56908c 100644 --- a/docs/tips.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``` \ No newline at end of file +```kubectl get nodes``` From e69fdd39882f8dd2a99b9131b5177dd9f5b529b4 Mon Sep 17 00:00:00 2001 From: Willem Mali Date: Wed, 14 Jun 2017 23:22:10 +0200 Subject: [PATCH 2/2] spelled out abbreviations, moved HA example to HA docs, integrated some other suggestions from @chrislovecn --- README.md | 28 ++-------------------------- docs/README.md | 26 +++++++++++--------------- docs/advanced_create.md | 20 -------------------- docs/high_availability.md | 34 +++++++++++++++++++++++++++++++--- 4 files changed, 44 insertions(+), 64 deletions(-) delete mode 100644 docs/advanced_create.md diff --git a/README.md b/README.md index f1adf28bc6..395bb4ed09 100644 --- a/README.md +++ b/README.md @@ -68,20 +68,6 @@ $ 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 @@ -151,20 +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. @@ -176,7 +152,7 @@ If you think you have found a bug please follow the instructions below. - 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. diff --git a/docs/README.md b/docs/README.md index c6378b3ee7..e350b800b3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,6 @@ Documentation Index =================== -This page serves as a categorized index for all `kops` documentation. - - Quick start ----------- * [Getting started on AWS](aws.md) @@ -13,8 +10,8 @@ Quick start Overview -------- -* [CLI](#cli) -* [Introspection](#introspection) +* [Command-line interface](#commandline-interface) +* [Inspection](#inspection) * [`kops` design documents](#kops-design-documents) * [Networking](#networking) * [Operations](#operations) @@ -23,7 +20,7 @@ Overview -### CLI ### +### Command-line interface ### * [CLI argument explanations](arguments.md) * [CLI reference](cli/kops.md) @@ -35,7 +32,7 @@ Overview * how to point kubectl to your `kops` cluster -### Introspection ### +### Inspection ### * [Download `kops` configuration](download_config.md) * methods to download the current generated `kops` configuration @@ -64,21 +61,20 @@ Overview * [Cluster addon manager](addon_manager.md) * [Cluster addons](addons.md) * [Cluster configuration management](changing_configuration.md) -* [Cluster with HA creation example](advanced_create.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 modify IG images and information on available/tested images -* [Label management](labels.md) - * for AWS instance tags and `k8s` node labels -* [`kube-up` to `kops` migration](upgrade_from_kubeup.md) -* [Secret management](secrets.md) -* [Single-master to multi-master migration](single-to-multi-master.md) -* [`k8s` updating](upgrade.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 ### diff --git a/docs/advanced_create.md b/docs/advanced_create.md deleted file mode 100644 index 67da1477f4..0000000000 --- a/docs/advanced_create.md +++ /dev/null @@ -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} -``` diff --git a/docs/high_availability.md b/docs/high_availability.md index c12422648e..1b149099e3 100644 --- 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} +``` +