From e4fd3f81a8bf72e67c7d43c071bbc4a7e7d43df6 Mon Sep 17 00:00:00 2001 From: Konstantinos Tsakalozos Date: Tue, 3 Oct 2017 03:35:36 +0300 Subject: [PATCH] Fixes in style and more on CDK (#5292) * Fixes in style and more on CDK * Addressing review comments --- docs/getting-started-guides/ubuntu/backups.md | 97 +++++++++--------- .../ubuntu/decommissioning.md | 8 +- .../getting-started-guides/ubuntu/glossary.md | 31 +++--- .../ubuntu/installation.md | 74 +++++++------- docs/getting-started-guides/ubuntu/logging.md | 4 +- .../ubuntu/monitoring.md | 1 + .../ubuntu/networking.md | 15 ++- docs/getting-started-guides/ubuntu/scaling.md | 21 ++-- .../getting-started-guides/ubuntu/security.md | 10 +- .../ubuntu/troubleshooting.md | 98 +++++++++---------- .../getting-started-guides/ubuntu/upgrades.md | 95 ++++++++++++------ .../ubuntu/validation.md | 39 ++++---- 12 files changed, 269 insertions(+), 224 deletions(-) diff --git a/docs/getting-started-guides/ubuntu/backups.md b/docs/getting-started-guides/ubuntu/backups.md index 8617c557ad..4d45bbc2dd 100644 --- a/docs/getting-started-guides/ubuntu/backups.md +++ b/docs/getting-started-guides/ubuntu/backups.md @@ -3,7 +3,11 @@ title: Backups --- {% capture overview %} -This page shows you how to backup and restore data from the different deployed services in a given cluster. +The state of a Kubernetes cluster is kept in the etcd datastore. +This page shows how to backup and restore the etcd shipped with +the Canonical Distribution of Kubernetes. Backing up application specific data, +normally stored in a persistent volume, is outside the scope of this +document. {% endcapture %} {% capture prerequisites %} @@ -11,19 +15,47 @@ This page assumes you have a working Juju deployed cluster. {% endcapture %} {% capture steps %} -## Exporting cluster data +## Snapshot etcd data -Exporting of cluster data is not supported at this time. +The `snapshot` action of the etcd charm allows the operator to snapshot +a running cluster's data for use in cloning, +backing up, or migrating to a new cluster. -## Restoring cluster data + juju run-action etcd/0 snapshot target=/mnt/etcd-backups -Importing of cluster data is not supported at this time. +- **param** target: destination directory to save the resulting snapshot archive. -## Exporting etcd data -Migrating etcd is a fairly easy task. +## Restore etcd data -Step 1: Snapshot your existing cluster. This is encapsulated in the `snapshot` +The etcd charm is capable of restoring its data from a cluster-data snapshot +via the `restore` action. +This comes with caveats and a very specific path to restore a cluster: +The cluster must be in a state of only having a single member. So it's best to +deploy a new cluster using the etcd charm, without adding any additional units. + +``` +juju deploy etcd new-etcd +``` + +The above code snippet will deploy a single unit of etcd, as 'new-etcd' + +``` +juju run-action etcd/0 restore target=/mnt/etcd-backups +``` + +Once the restore action has completed, evaluate the cluster health. If the unit +is healthy, you may resume scaling the application to meet your needs. + +- **param** target: destination directory to save the existing data. + +- **param** skip-backup: Don't backup any existing data. + + +## Migrating an etcd cluster +Using the above snapshot and restore operations, migrating etcd is a fairly easy task. + +**Step 1:** Snapshot your existing cluster. This is encapsulated in the `snapshot` action. ``` @@ -36,7 +68,7 @@ Results: Action queued with id: b46d5d6f-5625-4320-8cda-b611c6ae580c ``` -Step 2: Check the status of the action so you can grab the snapshot and verify +**Step 2:** Check the status of the action so you can grab the snapshot and verify the sum. The copy.cmd result output is a copy/paste command for you to download the exact snapshot that you just created. @@ -68,56 +100,24 @@ juju scp etcd/0:/home/ubuntu/etcd-snapshots/etcd-snapshot-2016-11-09-02.41.47.ta sha256sum etcd-snapshot-2016-11-09-02.41.47.tar.gz ``` -Step 3: Deploy the new cluster leader, and attach the snapshot: +**Step 3:** Deploy the new cluster leader, and attach the snapshot: ``` juju deploy etcd new-etcd --resource snapshot=./etcd-snapshot-2016-11-09-02.41.47.tar.gz ``` -Step 4: Re-Initialize the master with the data from the resource we just attached +**Step 4:** Reinitialize the master with the data from the resource we just attached in step 3. ``` juju run-action new-etcd/0 restore ``` -## Restoring etcd data -Allows the operator to restore the data from a cluster-data snapshot. This -comes with caveats and a very specific path to restore a cluster: - -The cluster must be in a state of only having a single member. So it's best to -deploy a new cluster using the etcd charm, without adding any additional units. - -``` -juju deploy etcd new-etcd -``` - -> The above code snippet will deploy a single unit of etcd, as 'new-etcd' - -``` -juju run-action etcd/0 restore target=/mnt/etcd-backups -``` - -Once the restore action has completed, evaluate the cluster health. If the unit -is healthy, you may resume scaling the application to meet your needs. - -- **param** target: destination directory to save the existing data. - -- **param** skip-backup: Don't backup any existing data. - -## Snapshot etcd data - -Allows the operator to snapshot a running clusters data for use in cloning, -backing up, or migrating Etcd clusters. - - juju run-action etcd/0 snapshot target=/mnt/etcd-backups - -- **param** target: destination directory to save the resulting snapshot archive. {% endcapture %} {% capture discussion %} -# Known Limitations +## Known Limitations #### Loss of PKI warning @@ -125,10 +125,11 @@ If you destroy the leader - identified with the `*` text next to the unit number all TLS pki will be lost. No PKI migration occurs outside of the units requesting and registering the certificates. -> Important: Mismanaging this configuration will result in locking yourself -> out of the cluster, and can potentially break existing deployments in very -> strange ways relating to x509 validation of certificates, which affects both -> servers and clients. +**Caution:** Mismanaging this configuration will result in locking yourself +out of the cluster, and can potentially break existing deployments in very +strange ways relating to x509 validation of certificates, which affects both +servers and clients. +{: .caution} #### Restoring from snapshot on a scaled cluster diff --git a/docs/getting-started-guides/ubuntu/decommissioning.md b/docs/getting-started-guides/ubuntu/decommissioning.md index 2d1b42c7e4..70e42e7f92 100644 --- a/docs/getting-started-guides/ubuntu/decommissioning.md +++ b/docs/getting-started-guides/ubuntu/decommissioning.md @@ -6,14 +6,18 @@ title: Decommissioning This page shows you how to properly decommission a cluster. {% endcapture %} -Warning: By the time you've reached this step you should have backed up your workloads and pertinent data, this section is for the complete destruction of a cluster. {% capture prerequisites %} This page assumes you have a working Juju deployed cluster. + +**Warning:** By the time you've reached this step you should have backed up your workloads and pertinent data; this section is for the complete destruction of a cluster. +{. warning} + {% endcapture %} {% capture steps %} -It is recommended to deploy individual Kubernetes clusters in their own models, so that there is a clean separation between environments. To remove a cluster first find out which model it's in with `juju list-models`. The controller reserves an `admin` model for itself. If you have chosen to not name your model it might show up as `default`. +## Destroy the Juju model +It is recommended to deploy individual Kubernetes clusters in their own models, so that there is a clean separation between environments. To remove a cluster first find out which model it's in with `juju list-models`. The controller reserves an `admin` model for itself. If you have chosen to not name your model it might show up as `default`. ``` $ juju list-models diff --git a/docs/getting-started-guides/ubuntu/glossary.md b/docs/getting-started-guides/ubuntu/glossary.md index 2afe083a82..c48aa82112 100644 --- a/docs/getting-started-guides/ubuntu/glossary.md +++ b/docs/getting-started-guides/ubuntu/glossary.md @@ -6,23 +6,18 @@ title: Glossary and Terminology This page explains some of the terminology used in deploying Kubernetes with Juju. {% endcapture %} -{% capture prerequisites %} -This page assumes you have a working Juju deployed cluster. +{% capture body %} + + +**controller** - The management node of a cloud environment. Typically you have one controller per cloud region, or more in HA environments. The controller is responsible for managing all subsequent models in a given environment. It contains the Juju API server and its underlying database. + +**model** - A collection of charms and their relationships that define a deployment. This includes machines and units. A controller can host multiple models. It is recommended to separate Kubernetes clusters into individual models for management and isolation reasons. + +**charm** - The definition of a service, including its metadata, dependencies with other services, required packages, and application management logic. It contains all the operational knowledge of deploying a Kubernetes cluster. Included charm examples are `kubernetes-core`, `easy-rsa`, `kibana`, and `etcd`. + +**unit** - A given instance of a service. These may or may not use up a whole machine, and may be colocated on the same machine. So for example you might have a `kubernetes-worker`, and `filebeat`, and `topbeat` units running on a single machine, but they are three distinct units of different services. + +**machine** - A physical node, these can either be bare metal nodes, or virtual machines provided by a cloud. {% endcapture %} - - -{% capture steps %} - -controller - The management node of a cloud environment. Typically you have one controller per cloud region, or more in HA environments. The controller is responsible for managing all subsequent models in a given environment. It contains the Juju API server and its underlying database. - -model - A collection of charms and their relationships that define a deployment. This includes machines and units. A controller can host multiple models. It is recommended to separate Kubernetes clusters into individual models for management and isolation reasons. - -charm - The definition of a service, including its metadata, dependencies with other services, required packages, and application management logic. It contains all the operational knowledge of deploying a Kubernetes cluster. Included charm examples are `kubernetes-core`, `easy-rsa`, `kibana`, and `etcd`. - -unit - A given instance of a service. These may or may not use up a whole machine, and may be colocated on the same machine. So for example you might have a `kubernetes-worker`, and `filebeat`, and `topbeat` units running on a single machine, but they are three distinct units of different services. - -machine - A physical node, these can either be bare metal nodes, or virtual machines provided by a cloud. -{% endcapture %} - -{% include templates/task.md %} +{% include templates/concept.md %} diff --git a/docs/getting-started-guides/ubuntu/installation.md b/docs/getting-started-guides/ubuntu/installation.md index 53245567b0..91d5848534 100644 --- a/docs/getting-started-guides/ubuntu/installation.md +++ b/docs/getting-started-guides/ubuntu/installation.md @@ -9,7 +9,22 @@ title: Setting up Kubernetes with Juju Ubuntu 16.04 introduced the [Canonical Distribution of Kubernetes](https://www.ubuntu.com/cloud/kubernetes), a pure upstream distribution of Kubernetes designed for production usage. This page shows you how to deploy a cluster. {% endcapture %} -Out of the box it comes with the following components on 9 machines: +{% capture prerequisites %} +- A working [Juju client](https://jujucharms.com/docs/2.2/reference-install); this does not have to be a Linux machine, it can also be Windows or OSX. +- A [supported cloud](#cloud-compatibility). + - Bare Metal deployments are supported via [MAAS](http://maas.io). Refer to the [MAAS documentation](http://maas.io/docs/) for configuration instructions. + - OpenStack deployments are currently only tested on Icehouse and newer. +- Network access to the following domains + - *.jujucharms.com + - gcr.io + - github.com + - Access to an Ubuntu mirror (public or private) +{% endcapture %} + + +{% capture steps %} +## Deployment overview +Out of the box the deployment comes with the following components on 9 machines: - Kubernetes (automated deployment, operations, and scaling) - Three node Kubernetes cluster with one master and two worker nodes. @@ -24,32 +39,34 @@ Out of the box it comes with the following components on 9 machines: - ETCD (distributed key value store) - Three unit cluster for reliability. -The Juju Kubernetes work is curated by a dedicated team of community members, +The Juju Kubernetes work is curated by the Big Software team at [Canonical Ltd](https://www.canonical.com/), let us know how we are doing. If you find any problems please open an [issue on our tracker](https://github.com/juju-solutions/bundle-canonical-kubernetes) so we can find them. -{% capture prerequisites %} -## Prerequisites +## Support Level -- A working [Juju client](https://jujucharms.com/docs/2.0/getting-started-general); this does not have to be a Linux machine, it can also be Windows or OSX. -- A [supported cloud](#cloud-compatibility). - - Bare Metal deployments are supported via [MAAS](http://maas.io). Refer to the [MAAS documentation](http://maas.io/docs/) for configuration instructions. - - OpenStack deployments are currently only tested on Icehouse and newer. -- Network access to the following domains - - *.jujucharms.com - - gcr.io - - github.com - - Access to an Ubuntu mirror (public or private) +IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level +-------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ---------------------------- +Amazon Web Services (AWS) | Juju | Ubuntu | flannel, calico* | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +OpenStack | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +Microsoft Azure | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +Google Compute Engine (GCE) | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +Joyent | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +Rackspace | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +VMWare vSphere | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) +Bare Metal (MAAS) | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) -### Configure Juju to use your cloud provider +For support level information on all solutions, see the [Table of solutions](/docs/getting-started-guides/#table-of-solutions) chart. + +## Configure Juju to use your cloud provider Deployment of the cluster is [supported on a wide variety of public clouds](#cloud-compatibility), private OpenStack clouds, or raw bare metal clusters. Bare metal deployments are supported via [MAAS](http://maas.io/). After deciding which cloud to deploy to, follow the [cloud setup page](https://jujucharms.com/docs/devel/getting-started) to configure deploying to that cloud. -Load your [cloud credentials](https://jujucharms.com/docs/2.0/credentials) for each +Load your [cloud credentials](https://jujucharms.com/docs/2.2/credentials) for each cloud provider you would like to use. In this example @@ -76,12 +93,10 @@ or, another example, this time on Azure: juju bootstrap azure/centralus ``` -You will need a controller node for each cloud or region you are deploying to. See the [controller documentation](https://jujucharms.com/docs/2.0/controllers) for more information. +You will need a controller node for each cloud or region you are deploying to. See the [controller documentation](https://jujucharms.com/docs/2.2/controllers) for more information. Note that each controller can host multiple Kubernetes clusters in a given cloud or region. -{% endcapture %} -{% capture steps %} ## Launch a Kubernetes cluster The following command will deploy the initial 9-node starter cluster. The speed of execution is very dependent of the performance of the cloud you're deploying to: @@ -190,7 +205,7 @@ resources from Juju by using **constraints**. You can increase the amount of CPU or memory (RAM) in any of the systems requested by Juju. This allows you to fine tune the Kubernetes cluster to fit your workload. Use flags on the bootstrap command or as a separate `juju constraints` command. Look to the -[Juju documentation for machine](https://jujucharms.com/docs/2.0/charms-constraints) +[Juju documentation for machine](https://jujucharms.com/docs/2.2/charms-constraints) details. ## Scale out cluster @@ -242,25 +257,10 @@ project on github.com: - [Bundle location](https://git.k8s.io/kubernetes/cluster/juju/bundles) - [Kubernetes charm layer location](https://git.k8s.io/kubernetes/cluster/juju/layers) - - [Canonical Kubernetes home](https://jujucharms.com/canonical-kubernetes/) + - [Canonical Kubernetes home](https://jujucharms.com/kubernetes) + - [Main issue tracker](https://github.com/juju-solutions/bundle-canonical-kubernetes) -Feature requests, bug reports, pull requests or any feedback would be much appreciated. +Feature requests, bug reports, pull requests and feedback are appreciated. {% endcapture %} -## Support Level - -IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level --------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ---------------------------- -Amazon Web Services (AWS) | Juju | Ubuntu | flannel, calico* | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -OpenStack | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -Microsoft Azure | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -Google Compute Engine (GCE) | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -Joyent | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -Rackspace | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -VMWare vSphere | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) -Bare Metal (MAAS) | Juju | Ubuntu | flannel, calico | [docs](/docs/getting-started-guides/ubuntu/) | | [Commercial](https://ubuntu.com/cloud/kubernetes), [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) - - -For support level information on all solutions, see the [Table of solutions](/docs/getting-started-guides/#table-of-solutions) chart. - {% include templates/task.md %} diff --git a/docs/getting-started-guides/ubuntu/logging.md b/docs/getting-started-guides/ubuntu/logging.md index ae7237a0a7..e8ddb10c80 100644 --- a/docs/getting-started-guides/ubuntu/logging.md +++ b/docs/getting-started-guides/ubuntu/logging.md @@ -10,7 +10,7 @@ This page will explain how logging works within a Juju deployed cluster. This page assumes you have a working Juju deployed cluster. {% endcapture %} - +{% capture steps %} ## Agent Logging The `juju debug-log` will show all of the consolidated logs of all the Juju agents running on each node of the cluster. This can be useful for finding out why a specific node hasn't deployed or is in an error state. These agent logs are located in `/var/lib/juju/agents` on every node. @@ -57,4 +57,6 @@ sudo systemctl restart jujud-machine-0.service ``` See the [official documentation](https://jujucharms.com/docs/stable/models-config) for more information about logging and other model settings in Juju. +{% endcapture %} +{% include templates/task.md %} diff --git a/docs/getting-started-guides/ubuntu/monitoring.md b/docs/getting-started-guides/ubuntu/monitoring.md index ba6e1ff99a..2bd5de0301 100644 --- a/docs/getting-started-guides/ubuntu/monitoring.md +++ b/docs/getting-started-guides/ubuntu/monitoring.md @@ -5,6 +5,7 @@ title: Monitoring {% capture overview %} This page shows how to connect various logging solutions to a Juju deployed cluster. {% endcapture %} + {% capture prerequisites %} This page assumes you have a working Juju deployed cluster. {% endcapture %} diff --git a/docs/getting-started-guides/ubuntu/networking.md b/docs/getting-started-guides/ubuntu/networking.md index b0b805f73c..5b5d84e16e 100644 --- a/docs/getting-started-guides/ubuntu/networking.md +++ b/docs/getting-started-guides/ubuntu/networking.md @@ -3,20 +3,19 @@ title: Networking --- {% capture overview %} -This page shows how to the various network portions of a cluster work, and how to configure them. +Kubernetes supports the [Container Network Interface (CNI)](https://github.com/containernetworking/cni). +This is a network plugin architecture that allows you to use whatever +Kubernetes-friendly SDN you want. Currently this means support for Flannel. + +This page shows how to the various network portions of a cluster work, and how to configure them. {% endcapture %} {% capture prerequisites %} This page assumes you have a working Juju deployed cluster. {% endcapture %} -Kubernetes supports the [Container Network Interface (CNI)](https://github.com/containernetworking/cni). -This is a network plugin architecture that allows you to use whatever -Kubernetes-friendly SDN you want. Currently this means support for Flannel. {% capture steps %} -# Flannel - -## Usage +## Flannel The flannel charm is a [subordinate](https://jujucharms.com/docs/stable/authors-subordinate-applications). @@ -31,7 +30,7 @@ juju add-relation flannel kubernetes-master juju add-relation flannel etcd ``` -## Configuration +### Configuration **iface** The interface to configure the flannel SDN binding. If this value is empty string or undefined the code will attempt to find the default network diff --git a/docs/getting-started-guides/ubuntu/scaling.md b/docs/getting-started-guides/ubuntu/scaling.md index b8ef81c758..c630bbbf77 100644 --- a/docs/getting-started-guides/ubuntu/scaling.md +++ b/docs/getting-started-guides/ubuntu/scaling.md @@ -5,9 +5,9 @@ title: Scaling {% capture overview %} This page shows how to horizontally scale master and worker nodes on a cluster. {% endcapture %} + {% capture prerequisites %} This page assumes you have a working Juju deployed cluster. -{% endcapture %} Any of the applications can be scaled out post-deployment. The charms update the status messages with progress, so it is recommended to run. @@ -15,14 +15,21 @@ update the status messages with progress, so it is recommended to run. ``` watch -c juju status --color ``` +{% endcapture %} + {% capture steps %} ## Kubernetes masters -The provided Kubernetes master nodes act as a control plane for the cluster. The deployment has been designed so that these nodes can be scaled independently of worker nodes to allow for more operational flexibility. To scale a master node up, simply execute: +The provided Kubernetes master nodes act as a control plane for the cluster. +The deployment has been designed so that these nodes can be scaled independently +of worker nodes to allow for more operational flexibility. +To scale a master node up, simply execute: juju add-unit kubernetes-master -This will add another master node to the control plane. See the [building high-availability clusters](/docs/admin/high-availability) section of the documentation for more information. +This will add another master node to the control plane. +See the [building high-availability clusters](/docs/admin/high-availability) +section of the documentation for more information. ## Kubernetes workers @@ -65,15 +72,17 @@ juju add-unit etcd Shrinking of an etcd cluster after growth is not recommended. -## Juju Controller +## Juju controller -A single node is responsible for coordinating with all the Juju agents on each machine that manage Kubernetes, it is called the controller node. For production deployments it is recommended to enable HA of the controller node: +A single node is responsible for coordinating with all the Juju agents +on each machine that manage Kubernetes; it is called the controller node. +For production deployments it is recommended to enable HA of the controller node: juju enable-ha Enabling HA results in 3 controller nodes, this should be sufficient for most use cases. 5 and 7 controller nodes are also supported for extra large deployments. -Refer to the [Juju HA controller documentation](https://jujucharms.com/docs/2.0/controllers-ha) for more information. +Refer to the [Juju HA controller documentation](https://jujucharms.com/docs/2.2/controllers-ha) for more information. {% endcapture %} {% include templates/task.md %} \ No newline at end of file diff --git a/docs/getting-started-guides/ubuntu/security.md b/docs/getting-started-guides/ubuntu/security.md index cc014524e4..7b26785a22 100644 --- a/docs/getting-started-guides/ubuntu/security.md +++ b/docs/getting-started-guides/ubuntu/security.md @@ -3,22 +3,24 @@ title: Security Considerations --- {% capture overview %} +By default all connections between every provided node are secured via TLS by easyrsa, including the etcd cluster. + This page explains the security considerations of a deployed cluster and production recommendations. {% endcapture %} {% capture prerequisites %} This page assumes you have a working Juju deployed cluster. {% endcapture %} -By default all connections between every provided node is secured via TLS by easyrsa, including the etcd cluster. +{% capture steps %} ## Implementation -The TLS and easyrsa implementations use the following [layers](https://jujucharms.com/docs/2.0/developer-layers). +The TLS and easyrsa implementations use the following [layers](https://jujucharms.com/docs/2.2/developer-layers). [layer-tls-client](https://github.com/juju-solutions/layer-tls-client) [layer-easyrsa](https://github.com/juju-solutions/layer-easyrsa) -{% capture steps %} + ## Limiting ssh access By default the administrator can ssh to any deployed node in a cluster. You can mass disable ssh access to the cluster nodes by issuing the following command. @@ -27,7 +29,7 @@ By default the administrator can ssh to any deployed node in a cluster. You can Note: The Juju controller node will still have open ssh access in your cloud, and will be used as a jump host in this case. -Refer to the [model management](https://jujucharms.com/docs/2.0/models) page in the Juju documentation for instructions on how to manage ssh keys. +Refer to the [model management](https://jujucharms.com/docs/2.2/models) page in the Juju documentation for instructions on how to manage ssh keys. {% endcapture %} {% include templates/task.md %} diff --git a/docs/getting-started-guides/ubuntu/troubleshooting.md b/docs/getting-started-guides/ubuntu/troubleshooting.md index 37fc19e0fd..807f2bbaf2 100644 --- a/docs/getting-started-guides/ubuntu/troubleshooting.md +++ b/docs/getting-started-guides/ubuntu/troubleshooting.md @@ -66,7 +66,7 @@ Will automatically ssh you to the 3rd worker unit. This will automatically ssh you to the easyrsa unit. -## Collecting Debug information +## Collecting debug information Sometimes it is useful to collect all the information from a node to share with a developer so problems can be identifying. This section will deal on how to use the debug action to collect this information. The debug action is only supported on `kubernetes-worker` nodes. @@ -140,71 +140,69 @@ This is caused by the API load balancer not forwarding ports in the context of t 1. Expose the Kubernetes Master service -``` -juju expose kubernetes-master -``` + ``` + juju expose kubernetes-master + ``` -2. Identify the public IP address of one of your masters +1. Identify the public IP address of one of your masters -``` -juju status kubernetes-master -Model Controller Cloud/Region Version -production k8s-admin aws/us-east-1 2.0.0 + ``` + juju status kubernetes-master + Model Controller Cloud/Region Version + production k8s-admin aws/us-east-1 2.0.0 -App Version Status Scale Charm Store Rev OS Notes -flannel 0.6.1 active 1 flannel jujucharms 7 ubuntu -kubernetes-master 1.5.1 active 1 kubernetes-master jujucharms 10 ubuntu exposed + App Version Status Scale Charm Store Rev OS Notes + flannel 0.6.1 active 1 flannel jujucharms 7 ubuntu + kubernetes-master 1.5.1 active 1 kubernetes-master jujucharms 10 ubuntu exposed -Unit Workload Agent Machine Public address Ports Message -kubernetes-master/0* active idle 5 54.210.100.102 6443/tcp Kubernetes master running. - flannel/0 active idle 54.210.100.102 Flannel subnet 10.1.50.1/24 + Unit Workload Agent Machine Public address Ports Message + kubernetes-master/0* active idle 5 54.210.100.102 6443/tcp Kubernetes master running. + flannel/0 active idle 54.210.100.102 Flannel subnet 10.1.50.1/24 -Machine State DNS Inst id Series AZ -5 started 54.210.100.102 i-002b7150639eb183b xenial us-east-1a + Machine State DNS Inst id Series AZ + 5 started 54.210.100.102 i-002b7150639eb183b xenial us-east-1a -Relation Provides Consumes Type -certificates easyrsa kubernetes-master regular -etcd etcd flannel regular -etcd etcd kubernetes-master regular -cni flannel kubernetes-master regular -loadbalancer kubeapi-load-balancer kubernetes-master regular -cni kubernetes-master flannel subordinate -cluster-dns kubernetes-master kubernetes-worker regular -cni kubernetes-worker flannel subordinate -``` + Relation Provides Consumes Type + certificates easyrsa kubernetes-master regular + etcd etcd flannel regular + etcd etcd kubernetes-master regular + cni flannel kubernetes-master regular + loadbalancer kubeapi-load-balancer kubernetes-master regular + cni kubernetes-master flannel subordinate + cluster-dns kubernetes-master kubernetes-worker regular + cni kubernetes-worker flannel subordinate + ``` -In this context the public IP address is 54.210.100.102. + In this context the public IP address is 54.210.100.102. -If you want to access this data programmatically you can use the JSON output: + If you want to access this data programmatically you can use the JSON output: -``` -juju show-status kubernetes-master --format json | jq --raw-output '.applications."kubernetes-master".units | keys[]' -54.210.100.102 -``` + ``` + juju show-status kubernetes-master --format json | jq --raw-output '.applications."kubernetes-master".units | keys[]' + 54.210.100.102 + ``` -3. Update the kubeconfig file +1. Update the kubeconfig file -Identify the kubeconfig file or section used for this cluster, and edit the server configuration. + Identify the kubeconfig file or section used for this cluster, and edit the server configuration. -By default, it will look like ```https://54.213.123.123:443```. Replace it with the Kubernetes Master endpoint ```https://54.210.100.102:6443``` and save. + By default, it will look like ```https://54.213.123.123:443```. Replace it with the Kubernetes Master endpoint ```https://54.210.100.102:6443``` and save. -Note that the default port used by CDK for the Kubernetes Master API is 6443 while the port exposed by the load balancer is 443. + Note that the default port used by CDK for the Kubernetes Master API is 6443 while the port exposed by the load balancer is 443. -4. Start helming again! +1. Start helming again! -``` -helm install --debug -Created tunnel using local port: '36749' -SERVER: "localhost:36749" -CHART PATH: /home/ubuntu/.helm/ -NAME: -... -... -``` + ``` + helm install --debug + Created tunnel using local port: '36749' + SERVER: "localhost:36749" + CHART PATH: /home/ubuntu/.helm/ + NAME: + ... + ... + ``` -## etcd - -## Kubernetes +## Logging and monitoring By default there is no log aggregation of the Kubernetes nodes, each node logs locally. It is recommended to deploy the Elastic Stack for log aggregation if you desire centralized logging. {% endcapture %} diff --git a/docs/getting-started-guides/ubuntu/upgrades.md b/docs/getting-started-guides/ubuntu/upgrades.md index d065993f28..a06a56540e 100644 --- a/docs/getting-started-guides/ubuntu/upgrades.md +++ b/docs/getting-started-guides/ubuntu/upgrades.md @@ -9,29 +9,54 @@ This page will outline how to manage and execute a Kubernetes upgrade. {% capture prerequisites %} This page assumes you have a working deployed cluster. -## Assumptions +**Warning:** You should always back up all your data before attempting an upgrade. +Don't forget to include the workload inside your cluster! +Refer to the [backup documentation](/docs/getting-started-guides/ubuntu/backups). +{: .warning} -You should always back up all your data before attempting an upgrade. Don't forget to include the workload inside your cluster! Refer to the [backup documentation](/docs/getting-started-guides/ubuntu/backups). {% endcapture %} {% capture steps %} -## Preparing for an Upgrade +## Patch kubernetes upgrades eg 1.7.0 -> 1.7.1 -See if upgrades are available. The Kubernetes charms are updated bi-monthly and mentioned in the Kubernetes release notes. Important operational considerations and change in behaviour will always be documented in the release notes. +Clusters are transparently upgraded to the latest Kubernetes patch release. +To be clear, a cluster deployed using the 1.7/stable channel +will transparently receive unattended upgrades for the 1.7.X Kubernetes +releases. +The upgrade causes no disruption to the operation of the cluster and requires +no intervention from a cluster administrator. +Each patch release is evaluated by the +Canonical Kubernetes Distribution team. +Once a patch release passes internal testing and is deemed safe for upgrade, +it is packaged in snap format and pushed to the stable channel. -You can use `juju status` to see if an upgrade is available. There will either be an upgrade to kubernetes or etcd, or both. -# Upgrade etcd +## Upgrading a minor Kubernetes release eg 1.7.1 -> 1.8.0 -Backing up etcd requires an export and snapshot, refer to the [backup documentation](/docs/getting-started-guides/ubuntu/backups) to create a snapshot. After the snapshot upgrade the etcd service with: + +The Kubernetes charms follow the Kubernetes releases. Please consult +your support plan on the upgrade frequency. Important operational considerations +and changes in behaviour will always be documented in the release notes. + +You can use `juju status` to see if an upgrade is available. +There may be an upgrade available for kubernetes, ectd, or both. + +### Upgrade etcd + +Backing up etcd requires an export and snapshot, refer to the +[backup documentation](/docs/getting-started-guides/ubuntu/backups) to create a snapshot. +After the snapshot upgrade the etcd service with: juju upgrade-charm etcd -This will handle upgrades between minor versions of etcd. Major upgrades from etcd 2.x to 3.x are currently unsupported. Instead, data will be run in etcdv2 stores over the etcdv3 api. +This will handle upgrades between minor versions of etcd. Major upgrades from +etcd 2.x to 3.x are currently unsupported. Instead, data will be run in etcdv2 stores over the etcdv3 api. -# Upgrade Kubernetes +### Upgrade Kubernetes -The Kubernetes Charms use snap channels to drive payloads. The channels are defined by `X.Y/channel` where `X.Y` is the `major.minor` release of Kubernetes (e.g. 1.6) and `channel` is one of the four following channels: +The Kubernetes Charms use snap channels to drive payloads. +The channels are defined by `X.Y/channel` where `X.Y` is the `major.minor` release +of Kubernetes (e.g. 1.6) and `channel` is one of the four following channels: | Channel name | Description | | ------------------- | ------------ | @@ -40,15 +65,19 @@ The Kubernetes Charms use snap channels to drive payloads. The channels are defi | beta | Latest alpha or beta of Kubernetes for that minor release | | edge | Nightly builds of that minor release of Kubernetes | -If a release isn't available, the next highest channel is used. For example, 1.6/beta will load `/candidate` or `/stable` depending on availability of release. Development versions of Kubernetes are available in that minor releases edge channel. There is no guarantee that edge or master will work with the current charms. +If a release isn't available, the next highest channel is used. +For example, 1.6/beta will load `/candidate` or `/stable` depending on availability of release. +Development versions of Kubernetes are available in the edge channel for each minor release. +There is no guarantee that edge snaps will work with the current charms. -## Master Upgrades +### Master Upgrades First you need to upgrade the masters: juju upgrade-charm kubernetes-master -NOTE: Always upgrade the masters before the workers. +**Node:** Always upgrade the masters before the workers. +{: .note} Once the latest charm is deployed, the channel for Kubernetes can be selected by issuing the following: @@ -57,13 +86,17 @@ Once the latest charm is deployed, the channel for Kubernetes can be selected by Where `x` is the minor version of Kubernetes. For example, `1.6/stable`. See above for Channel definitions -## Worker Upgrades +### Worker Upgrades -Two methods of upgrading workers are supported. [Blue/Green Deployment](http://martinfowler.com/bliki/BlueGreenDeployment.html) and upgrade-in-place. Both methods are provided for operational flexibility and both are supported and tested. Blue/Green will require more hardware up front than inplace, but is a safer upgrade route. +Two methods of upgrading workers are supported. +[Blue/Green Deployment](http://martinfowler.com/bliki/BlueGreenDeployment.html) +and upgrade-in-place. Both methods are provided for operational flexibility and both +are supported and tested. Blue/Green will require more hardware up front than in-place, +but is a safer upgrade route. -## Blue/Green Upgrade +#### Blue/green worker upgrade -Given the following deployment, where the workers are named kubernetes-alpha. +Given a deployment where the workers are named kubernetes-alpha. Deploy new worker(s): @@ -81,42 +114,40 @@ Tear down old workers with: juju remove-application kubernetes-alpha -## In place worker upgrade +#### In place worker upgrade juju upgrade-charm kubernetes-worker juju config kubernetes-worker channel=1.x/stable -Where `x` is the minor version of Kubernetes. For example, `1.6/stable`. See above for Channel definitions. Once you've configured kubernetes-worker with the appropriate channel, run the upgrade action on each worker: +Where `x` is the minor version of Kubernetes. For example, `1.6/stable`. +See above for Channel definitions. Once you've configured kubernetes-worker with the appropriate channel, +run the upgrade action on each worker: juju run-action kubernetes-worker/0 upgrade juju run-action kubernetes-worker/1 upgrade ... -# Verify upgrade +### Verify upgrade `kubectl version` should return the newer version. -It is recommended to rerun a [cluster validation](/docs/getting-started-guides/ubuntu/validation) to ensure that the cluster upgrade has successfully completed. +It is recommended to rerun a [cluster validation](/docs/getting-started-guides/ubuntu/validation) +to ensure that the cluster upgrade has successfully completed. -# Upgrade Flannel +### Upgrade Flannel -Upgrading flannel can be done at any time, it is independent of Kubernetes upgrades. Be advised that networking is interrupted during the upgrade. You can initiate a flannel upgrade: +Upgrading flannel can be done at any time, it is independent of Kubernetes upgrades. +Be advised that networking is interrupted during the upgrade. You can initiate a flannel upgrade: juju upgrade-charm flannel -# Upgrade easyrsa +### Upgrade easyrsa -Upgrading easyrsa can be done at any time, it is independent of Kubernetes upgrades. Upgrading easyrsa should result in zero downtime as it is not a running service: +Upgrading easyrsa can be done at any time, it is independent of Kubernetes upgrades. +Upgrading easyrsa should result in zero downtime as it is not a running service: juju upgrade-charm easyrsa -## Rolling back etcd - -At this time rolling back etcd is unsupported. - -## Rolling back Kubernetes - -At this time rolling back Kubernetes is unsupported. {% endcapture %} {% include templates/task.md %} diff --git a/docs/getting-started-guides/ubuntu/validation.md b/docs/getting-started-guides/ubuntu/validation.md index 445bd6e4f6..b842db82c7 100644 --- a/docs/getting-started-guides/ubuntu/validation.md +++ b/docs/getting-started-guides/ubuntu/validation.md @@ -1,9 +1,10 @@ --- -title: Validation +title: Validation - End-to-end Testing --- {% capture overview %} -This page will outline how to ensure that a Juju deployed Kubernetes cluster has stood up correctly and is ready to accept workloads. +This page will outline how to ensure that a Juju-deployed Kubernetes +cluster has stood up correctly and is ready to accept workloads. {% endcapture %} {% capture prerequisites %} @@ -11,9 +12,7 @@ This page assumes you have a working Juju deployed cluster. {% endcapture %} {% capture steps %} -# Validation - -## End to End Testing +## End-to-end testing End-to-end (e2e) tests for Kubernetes provide a mechanism to test end-to-end behavior of the system, and is the last signal to ensure end user operations @@ -26,14 +25,16 @@ The primary objectives of the e2e tests are to ensure a consistent and reliable behavior of the kubernetes code base, and to catch hard-to-test bugs before users do, when unit and integration tests are insufficient. -### Usage +### Deploy kubernetes-e2e charm -To deploy the end-to-end test suite, you need to relate the `kubernetes-e2e` charm to your existing kubernetes-master nodes and easyrsa: +To deploy the end-to-end test suite, you need to relate the `kubernetes-e2e` charm +to your existing kubernetes-master nodes and easyrsa: ``` juju deploy cs:~containers/kubernetes-e2e -juju add-relation kubernetes-e2e kubernetes-master juju add-relation kubernetes-e2e easyrsa +juju add-relation kubernetes-e2e:kubernetes-master kubernetes-master:kube-api-endpoint +juju add-relation kubernetes-e2e:kube-control kubernetes-master:kube-control ``` Once the relations have settled, you can do `juju status` until the workload status results in @@ -85,13 +86,13 @@ a deployed cluster. The following example will skip the `Flaky`, `Slow`, and juju run-action kubernetes-e2e/0 test skip='\[(Flaky|Slow|Feature:.*)\]' -> Note: the escaping of the regex due to how bash handles brackets. +**Note:** the escaping of the regex due to how bash handles brackets. +{: .note} To see the different types of tests the Kubernetes end-to-end charm has access -to, we encourage you to see the upstream documentation on the different types -of tests, and to strongly understand what subsets of the tests you are running. - -[Kinds of tests](https://git.k8s.io/community/contributors/devel/e2e-tests.md#kinds-of-tests) +to, we encourage you to see the [upstream documentation on the different types +of tests](https://git.k8s.io/community/contributors/devel/e2e-tests.md#kinds-of-tests), +and to thoroughly understand what subsets of the tests you are running. ### More information on end-to-end testing @@ -106,11 +107,12 @@ places. The raw output of the e2e run is available in the `juju show-action-outp command, as well as a flat file on disk on the `kubernetes-e2e` unit that executed the test. -> Note: The results will only be available once the action has -completed the test run. End-to-end testing can be quite time intensive. Often -times taking **greater than 1 hour**, depending on configuration. +**Note:** The results will only be available once the action has +completed the test run. End-to-end testing can be quite time consuming, often +taking more than 1 hour, depending on configuration. +{: .note} -##### Flat file +##### Accessing the results in a flat file Here's how to copy the output out as a file: @@ -149,7 +151,8 @@ on the kubernetes-worker units. ## Upgrading the e2e tests -The e2e tests are always expanding, you can see if there's an upgrade available by running `juju status kubernetes-e2e`. +The e2e tests are always expanding; you can see if there's an upgrade +available by running `juju status kubernetes-e2e`. When an upgrade is available, upgrade your deployment: