From 376be8c6fc5704aec999a45440d0e6128c03b395 Mon Sep 17 00:00:00 2001 From: Lars Kellogg-Stedman Date: Thu, 25 Jun 2015 12:51:19 -0400 Subject: [PATCH] some README updates Change-Id: I6b042250555a88a14660329bd232c9b887bba509 --- README.md | 98 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 62 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 34b2114..9386597 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,80 @@ -A Kubernetes cluster with Heat -============================== +Deploying Atomic + Kubernetes with Heat +======================================= -These [Heat][] templates will deploy a [Kubernetes][] cluster that -supports automatic scaling based on CPU load. +These [Heat][] templates will deploy a cluster of Nova instances +running [Kubernetes][] on top of [Project Atomic][]. The cluster uses +[Flannel][] to provide an overlay network connecting pods deployed on +different nodes. + +You can determine the initial size of the cluster via a configuration +parameter when you deploy it, and the cluster will scale dynamically +(up to a specified maximum size) due to CPU load on the Kubernetes +nodes. [heat]: https://wiki.openstack.org/wiki/Heat [kubernetes]: https://github.com/GoogleCloudPlatform/kubernetes - -The cluster uses [Flannel][] to provide an overlay network connecting -pods deployed on different minions. - +[project atomic]: http://www.projectatomic.io/ [flannel]: https://github.com/coreos/flannel ## Requirements ### OpenStack -These templates will work with the Kilo version of Heat. They *may* -work with Juno as well as soon as [#1402894][] is resolved. +These templates will work with the Kilo version of Heat. +They will work with the Juno version of Heat as long as you have a +release that includes [this fix][] for bug [#1402894][]. +[this fix]: https://review.openstack.org/#/c/182446/ [#1402894]: https://bugs.launchpad.net/heat/+bug/1402894 +You should deploy some simple stacks in your environment to ensure +that Heat is configured correctly before attempting to use these +templates. + ### Guest image -These templates will work with either CentOS Atomic Host or Fedora 21 -Atomic. +These templates require an Atomic disk image. You can obtain disk +images from [Project Atomic][], as well as directly from [Fedora][] +and from [Red Hat][]. + +[fedora]: https://getfedora.org/en/cloud/download/atomic.html +[red hat]: https://access.redhat.com/articles/rhel-atomic-getting-started -You can enable the VXLAN backend for flannel by setting the -"flannel_use_vxlan" parameter to "true", but I have run into kernel -crashes using that backend with CentOS 7. It seems to work fine with -Fedora 21. +These templates are known to work with RHEL Atomic 7.1.2 and Fedora 22 +Atomic. ## Creating the stack -Creating an environment file `local.yaml` with parameters specific to -your environment: +These templates define several parameters that can be used to +configure the stack; for details see the `parameters` section of +`kubecluster.yaml`. While many of the parameters have reasonable +defaults, you will need to provide values for: - parameters: - ssh_key_name: lars - external_network: public - dns_nameserver: 192.168.200.1 - server_image: centos-7-atomic-20150101 +- `ssh_key_name` -- the name of an SSH key already installed in Nova + that will be used for accessing your Kubernetes nodes. + +- `server_image` -- the name of an image in Glance that will be used + to instantiate the nodes. + +You may need to provide a value for: -And then create the stack, referencing that environment file: +- `dns_nameserver` -- a nameserver that is reachable in your + environment. This defaults to one of the public Google nameservers + (8.8.8.8), which may not be accessible (or useful) in some internal + environments. - heat stack-create -f kubecluster.yaml -e local.yaml my-kube-cluster +To provide the parameter values to the template you will create an +environment file that may look something like this: + + parameters: + ssh_key_name: lars + server_image: fedora-atomic + dns_nameserver: 192.168.122.1 -You must provide values for: +You will provide this file via the `-e` argument to `heat +stack-create`: -- `ssh_key_name` -- `server_image` + heat stack-create -f kubecluster.yaml -e params.yaml my-kube-cluster ## Interacting with Kubernetes @@ -63,14 +88,15 @@ You can ssh into that server as the `minion` user: $ ssh minion@192.168.200.86 -And once logged in you can run `kubectl`, etc: +And once logged in you can run `kubectl` to interact with the +Kubernetes API: $ kubectl get minions NAME LABELS STATUS 10.0.0.4 Ready -You can log into your minions using the `minion` user as well. You -can get a list of minion addresses by running: +You can log into your nodes using the `minion` user as well. You +can get a list of node addresses by running: $ heat output-show my-kube-cluster kube_minions_external [ @@ -79,16 +105,16 @@ can get a list of minion addresses by running: ## Testing -The templates install an example Pod and Service description into +The templates install some example Pod and Service descriptions into `/etc/kubernetes/examples`. You can deploy this with the following commands: $ kubectl create -f /etc/kubernetes/examples/web.service - $ kubectl create -f /etc/kubernetes/examples/web.pod + $ kubectl create -f /etc/kubernetes/examples/web.replica -This will deploy a minimal webserver and a service. You can use -`kubectl get pods` and `kubectl get services` to see the results of -these commands. +This will deploy a minimal webserver and a corresponding service. You +can use `kubectl get pods` and `kubectl get services` to see the +results of these commands. ## License