chake 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e900187a5fdfbed5fb3712c249f00b23c66d05bc
-  data.tar.gz: 5024eaab5d4de0e7f30fd1f1839a2e690cb11fa3
+  metadata.gz: 6ccedd33bee72b8c2b029a07bdb3519447db80d6
+  data.tar.gz: e742e82cb94db00ab390a154babda6d784fa0d05
 SHA512:
-  metadata.gz: 5f2d124d8a2e00c90e15a27de6a8c3db136e130b8cc9258790d22ae70a8f0269c1d6b5bde4144d51590a1e2e99aff6fd99a748a1ef83f22d3fd9a065ba24bfe1
-  data.tar.gz: 34f103cc2a3997dbc178589d29da4c6bac88056db49266483cac298be935a8985a58120dda521b7b7f20adf4ab52ef36e6d554dd5567166252d4a6296d3fed6f
+  metadata.gz: 210582e1e859931e33b3fb80af745699980414859e153f1f33be2040b01786f7bc853c96c0da61f8569bed3ddd66339498fb5223a8dd0499cffe70fb26e8a92b
+  data.tar.gz: 8e00de96b07d27cd1cdc444ce625daa02c2ea3cf5259487519cd991321d99e164158c8b886ab549ed0956b0149915dd8775d58c60be4cfbd2d1b45d0da1f558b

data/.gitignore

@@ -17,3 +17,4 @@ test/version_tmp
 tmp
 /examples/test/nodes.yaml
 /examples/test/.tmp
+.*.html

data/ChangeLog.md

@@ -1,3 +1,10 @@
+# 0.3.2
+
+* Now finally, hopefully, really fix RPM builds
+* chake init: rename 'myhost' → 'basics'
+* The official home is on gitlab
+* Completed basic documentation
+
 # 0.3.1
 
 * Fix setting hostname when bootstrapping

data/README.md

@@ -6,7 +6,7 @@ Simple host management with chef and rake. No chef server required.
 
     $ gem install chake
 
-## Usage
+## Creating the repository
 
 Require chake on your `Rakefile`:
 
@@ -16,43 +16,179 @@ require 'chake'
 
 Initializing the repository:
 
-    $ rake init
+```
+$ chake init
+[create] nodes.yaml
+[create] config.rb
+[ mkdir] config/roles
+[ mkdir] cookbooks/basics/recipes/
+[create] cookbooks/basics/recipes/default.rb
+[create] Rakefile
+```
 
+A brief explanation of the created files:
 
-Important files that are generated:
+| File | Description |
+|-----+-------|
+| `nodes.yaml`  | where you will list the hosts you will be managing, and what recipes to apply to each of them. |
+| `config.rb` | contains the chef-solo configuration. You can modify it, but usually you won't need to. |
+| `config/roles` | directory is where you can put your role definitions. |
+| `cookbooks` | directory where you will store your cookbooks. A sample cookbook called "basics" is created, but feel free to remove it and add actual cookbooks. |
+| `Rakefile` | Contains just the `require 'chake'` line. You can augment it with other tasks specific to your intrastructure. |
 
-```
-config.rb
-nodes.yaml
-config/
-config/roles/
-cookbooks/
-cookbooks/myhost/
-cookbooks/myhost/recipes/
-cookbooks/myhost/recipes/default.rb
+After the repository is created, you can call either `chake` or `rake`, as they
+are completely equivalent.
+
+## Managing nodes and recipes
 
+Just after you created your repository, the contents of `nodes.yaml` is the
+following:
+
+```yaml
+host1.mycompany.com:
+  run_list:
+    - recipe[basics]
 ```
 
-* `nodes.yaml`, where you will list the hosts you will be managing.
-* a `cookbooks` directory where you will store your cookbooks. A sample
-  cookbook called "myhost" is created, but feel free to remove it and add
-  actual cookbooks.
+You can list your hosts with `rake nodes`:
 
+```
+$ rake nodes
+host1.mycompany.com                      ssh
+```
 
-Sample `nodes.yaml`:
+To add more nodes, just append to `nodes.yaml`:
 
 ```yaml
 host1.mycompany.com:
-    run_list:
-        - recipe[common]
-        - recipe[webserver]
+  run_list:
+    - recipe[basics]
 host2.mycompany.com:
-    run_list:
-        - recipe[common]
-        - recipe[mailserver]
+  run_list:
+    - recipes[basics]
+```
+
+And chake now knows about your new node:
+
+```
+$ rake nodes
+host1.mycompany.com                      ssh
+host2.mycompany.com                      ssh
+```
+
+## Preparings nodes to be managed
+
+Nodes has very few requirements to be managed with `chake`:
+
+- The node must be accessible via SSH.
+- The node must have `sudo` installed.
+- The user you connect to the node must either be `root`, or be allowed to run
+  `sudo`.
+
+**A note on password prompts:** every time chake calls ssh on a node, you may
+be required to type in your password; every time chake calls sudo on the node,
+you may be require to type in your password. For managaing one or two nodes
+this is probably fine, but for larger numbers it is not practical. To avoid
+password prompts, you can:
+
+- configure SSH key authentication.
+    - this is more secure than using passwords, anyway.
+    - bonus points: disable password authentication completely, and only allow
+      key-based authentication
+- configure passwordless `sudo` access for your user on the server
+
+## Applying cookbooks
+
+To apply the configuration to all nodes, run
+
+```bash
+$ rake converge
+```
+
+To apply the configuration to a single node, run
+
+```bash
+$ rake converge:$NODE
+```
+
+## Writing cookbooks
+
+Since chake is actually a wrapper for Chef Solo, you should read the [chef
+documentation](https://docs.chef.io/). In special, look at the [Chef Solo
+Documentation](https://docs.chef.io/chef_solo.html).
+
+## The node bootstrapping process
+
+When chake acts on a node for the first time, it has to bootstrap it. The
+bootstrapping process includes doing the following:
+
+- installing chef and rsync
+- disabling the chef client daemon
+- setting up the hostname
+
+## Node URLs
+
+The keys in the hash that is represented in `nodes.yaml` is a node URL. All
+components of the URL but the hostname are optional, so just listing hostnames
+is the simplest form of specifying your nodes. Here are all the components of
+the node URLs:
+
+```
+[backend://][username@]hostname[:port][/path]
+```
+
+|Parameter|Meaning|Default value|
+|---------|-------|-------------|
+| backend | backend to use to connect to the host. `ssh` or `local` | `ssh` |
+| username | user name to connect with | The username on your local workstation |
+| hostname | the hostname to connect to | _none_ |
+| port | port number to connect to | 22 |
+| /path | where to store the cookbooks at the node | `/var/tmp/chef.$USERNAME` |
+
+
+## Extra features
+
+### Encrypted files
+
+Any files ending matching `*.gpg` and `*.asc` will be decrypted with GnuPG
+before being sent to the node. You can use them to store passwords and other
+sensitive information (SSL keys, etc) in the repository together with the rest
+of the configuration.
+
+### repository-local SSH configuration
+
+If you need special SSH configuration parameters, you can create a file called
+`.ssh_config` in at the root of your repository, and chake will use it when
+calling `ssh`.
+
+### Converging local host
+
+If you want to manage your local workstation with chake, you can declare a local node like this in `nodes.yaml`:
+
+```yaml
+local://thunderbolt:
+  run_list:
+    - role[workstation]
+```
+
+To apply the configuration to the local host, you can use the conventional
+`rake converse:thunderbolt`, or the special target `rake local`.
+
+When converging all nodes, `chake` will skip nodes that are declared with the
+`local://` backend and whose hostname does not match the hostname  in the
+declaration. For example:
+
+```yaml
+local://desktop:
+  run_list:
+    - role[workstation]
+local://laptop:
+  run_list:
+    - role[workstation]
 ```
 
-Check the output of `rake -T` to see what else you can do.
+When you run `rake converge` on `desktop`, `laptop` will be skipped, and
+vice-versa.
 
 ## Contributing
 

data/chake.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["terceiro@softwarelivre.org"]
   spec.summary       = %q{Simple host management with chef and rake. No chef server required.}
   spec.description   = %q{chake provides a set of rake tasks that you can use to manage any number of hosts via SSH. It doesn't require a chef server; all you need is a workstation from where you can SSH into all your hosts.}
-  spec.homepage      = "https://github.com/terceiro/chake"
+  spec.homepage      = "https://gitlab.com/terceiro/chake"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/chake.spec.erb

@@ -31,7 +31,7 @@ Requires: ruby, rubygem-rake
 %install
 %{__rm} -rf %{buildroot}
 mkdir -p %{gembuilddir}
-sed -i -e 's#spec.files\s*=.*#spec.files = Dir.glob('**/*')#' %{name}.gemspec
+sed -i -e 's#spec.files\s*=.*#spec.files = Dir.glob("**/*")#' %{name}.gemspec
 rake build
 gem install --local --install-dir %{gembuilddir} --force pkg/*.gem
 mkdir -p %{buildroot}/%{_bindir}

data/lib/chake.rb

@@ -19,9 +19,9 @@ task :init do
   else
     File.open('nodes.yaml', 'w') do |f|
       sample_nodes = <<EOF
-host1.my.tld:
+host1.mycompany.com:
   run_list:
-    - recipe[myhost]
+    - recipe[basics]
 EOF
       f.write(sample_nodes)
       puts "[create] nodes.yaml"
@@ -43,11 +43,11 @@ EOF
     FileUtils.mkdir_p 'config/roles'
     puts  '[ mkdir] config/roles'
   end
-  if !File.exist?('cookbooks/myhost/recipes')
-    FileUtils.mkdir_p 'cookbooks/myhost/recipes/'
-    puts  '[ mkdir] cookbooks/myhost/recipes/'
+  if !File.exist?('cookbooks/basics/recipes')
+    FileUtils.mkdir_p 'cookbooks/basics/recipes/'
+    puts  '[ mkdir] cookbooks/basics/recipes/'
   end
-  recipe = 'cookbooks/myhost/recipes/default.rb'
+  recipe = 'cookbooks/basics/recipes/default.rb'
   if File.exists?(recipe)
     puts "[exists] #{recipe}"
   else

data/lib/chake/version.rb

@@ -1,3 +1,3 @@
 module Chake
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chake
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Antonio Terceiro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-12 00:00:00.000000000 Z
+date: 2015-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -89,7 +89,7 @@ files:
 - spec/chake/backend_spec.rb
 - spec/chake/node_spec.rb
 - spec/spec_helper.rb
-homepage: https://github.com/terceiro/chake
+homepage: https://gitlab.com/terceiro/chake
 licenses:
 - MIT
 metadata: {}