From 017b88a92a106d9e104988c904165423cbad4d39 Mon Sep 17 00:00:00 2001 From: John Keiser Date: Tue, 9 Sep 2014 16:47:38 -0700 Subject: Add ChefFS rdoc, format existing ChefFS rdoc correctly --- lib/chef/chef_fs/chef_fs_data_store.rb | 54 +++++++++++++++++ lib/chef/chef_fs/config.rb | 67 +++++++++++++++++++++- .../chef_repository_file_system_root_dir.rb | 18 +++--- .../chef_fs/file_system/chef_server_root_dir.rb | 31 +++++----- 4 files changed, 148 insertions(+), 22 deletions(-) diff --git a/lib/chef/chef_fs/chef_fs_data_store.rb b/lib/chef/chef_fs/chef_fs_data_store.rb index 09a66a9ab2..484ab07390 100644 --- a/lib/chef/chef_fs/chef_fs_data_store.rb +++ b/lib/chef/chef_fs/chef_fs_data_store.rb @@ -27,7 +27,61 @@ require 'fileutils' class Chef module ChefFS + # + # Translation layer between chef-zero's DataStore (a place where it expects + # files to be stored) and ChefFS (the user's repository directory layout). + # + # chef-zero expects the data store to store files *its* way--for example, it + # expects get("nodes/blah") to return the JSON text for the blah node, and + # it expects get("cookbooks/blah/1.0.0") to return the JSON definition of + # the blah cookbook version 1.0.0. + # + # The repository is defined the way the *user* wants their layout. These + # two things are very similar in layout (for example, nodes are stored under + # the nodes/ directory and their filename is the name of the node). + # + # However, there are a few differences that make this more than just a raw + # file store: + # + # 1. Cookbooks are stored much differently. + # - chef-zero places JSON text with the checksums for the cookbook at + # /cookbooks/NAME/VERSION, and expects the JSON to contain URLs to the + # actual files, which are stored elsewhere. + # - The repository contains an actual directory with just the cookbook + # files and a metadata.rb containing a version #. There is no JSON to + # be found. + # - Further, if versioned_cookbooks is false, that directory is named + # /cookbooks/NAME and only one version exists. If versioned_cookbooks + # is true, the directory is named /cookbooks/NAME-VERSION. + # - Therefore, ChefFSDataStore calculates the cookbook JSON by looking at + # the files in the cookbook and checksumming them, and reading metadata.rb + # for the version and dependency information. + # - ChefFSDataStore also modifies the cookbook file URLs so that they point + # to /file_store/repo/ (the path to the actual file under the + # repository root). For example, /file_store/repo/apache2/metadata.rb or + # /file_store/repo/cookbooks/apache2/recipes/default.rb). + # + # 2. Sandboxes don't exist in the repository. + # - ChefFSDataStore lets cookbooks be uploaded into a temporary memory + # storage, and when the cookbook is committed, copies the files onto the + # disk in the correct place (/cookbooks/apache2/recipes/default.rb). + # 3. Data bags: + # - The Chef server expects data bags in /data/BAG/ITEM + # - The repository stores data bags in /data_bags/BAG/ITEM + # + # 4. JSON filenames are generally NAME.json in the repository (e.g. /nodes/foo.json). + # class ChefFSDataStore + # + # Create a new ChefFSDataStore + # + # ==== Arguments + # + # [chef_fs] + # A +ChefFS::FileSystem+ object representing the repository root. + # Generally will be a +ChefFS::FileSystem::ChefRepositoryFileSystemRoot+ + # object, created from +ChefFS::Config.local_fs+. + # def initialize(chef_fs) @chef_fs = chef_fs @memory_store = ChefZero::DataStore::MemoryStore.new diff --git a/lib/chef/chef_fs/config.rb b/lib/chef/chef_fs/config.rb index ca273b2cca..fcad6c919f 100644 --- a/lib/chef/chef_fs/config.rb +++ b/lib/chef/chef_fs/config.rb @@ -22,9 +22,74 @@ require 'chef/chef_fs/path_utils' class Chef module ChefFS # - # Helpers to take Chef::Config and create chef_fs and local_fs from it + # Helpers to take Chef::Config and create chef_fs and local_fs (ChefFS + # objects representing the server and local repository, respectively). # class Config + # + # Create a new Config object which can produce a chef_fs and local_fs. + # + # ==== Arguments + # + # [chef_config] + # A hash that looks suspiciously like +Chef::Config+. These hash keys + # include: + # + # :chef_repo_path:: + # The root where all local chef object data is stored. Mirrors + # +Chef::Config.chef_repo_path+ + # :cookbook_path, node_path, ...:: + # Paths to cookbooks/, nodes/, data_bags/, etc. Mirrors + # +Chef::Config.cookbook_path+, etc. Defaults to + # +/cookbooks+, etc. + # :repo_mode:: + # The directory format on disk. 'everything', 'hosted_everything' and + # 'static'. Default: autodetected based on whether the URL has + # "/organizations/NAME." + # :versioned_cookbooks:: + # If true, the repository contains cookbooks with versions in their + # name (apache2-1.0.0). If false, the repository just has one version + # of each cookbook and the directory has the cookbook name (apache2). + # Default: +false+ + # :chef_server_url:: + # The URL to the Chef server, e.g. https://api.opscode.com/organizations/foo. + # Used as the server for the remote chef_fs, and to "guess" repo_mode + # if not specified. + # :node_name:: The username to authenticate to the Chef server with. + # :client_key:: The private key for the user for authentication + # :environment:: The environment in which you are presently working + # :repo_mode:: + # The repository mode, :hosted_everything, :everything or :static. + # This determines the set of subdirectories the Chef server will offer + # up. + # :versioned_cookbooks:: Whether or not to include versions in cookbook names + # + # [cwd] + # The current working directory to base relative Chef paths from. + # Defaults to +Dir.pwd+. + # + # [options] + # A hash of other, not-suspiciously-like-chef-config options: + # :cookbook_version:: + # When downloading cookbooks, download this cookbook version instead + # of the latest. + # + # [ui] + # The object to print output to, with "output", "warn" and "error" + # (looks a little like a Chef::Knife::UI object, obtainable from + # Chef::Knife.ui). + # + # ==== Example + # + # require 'chef/chef_fs/config' + # config = Chef::ChefFS::Config.new + # config.chef_fs.child('cookbooks').children.each do |cookbook| + # puts "Cookbook on server: #{cookbook.name}" + # end + # config.local_fs.child('cookbooks').children.each do |cookbook| + # puts "Local cookbook: #{cookbook.name}" + # end + # def initialize(chef_config = Chef::Config, cwd = Dir.pwd, options = {}, ui = nil) @chef_config = chef_config @cwd = cwd diff --git a/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb b/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb index 050da60389..ac272d4c1a 100644 --- a/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb +++ b/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb @@ -42,15 +42,17 @@ class Chef # Create a new Chef Repository File System root. # # == Parameters - # - child_paths - a hash of child paths, e.g.: - # "nodes" => [ '/var/nodes', '/home/jkeiser/nodes' ], - # "roles" => [ '/var/roles' ], - # ... - # - root_paths - an array of paths representing the top level, where - # org.json, members.json, and invites.json will be stored. - # - chef_config - a hash of options that looks suspiciously like the ones + # [child_paths] + # A hash of child paths, e.g.: + # "nodes" => [ '/var/nodes', '/home/jkeiser/nodes' ], + # "roles" => [ '/var/roles' ], + # ... + # [root_paths] + # An array of paths representing the top level, where + # +org.json+, +members.json+, and +invites.json+ will be stored. + # [chef_config] - a hash of options that looks suspiciously like the ones # stored in Chef::Config, containing at least these keys: - # - :versioned_cookbooks - whether to include versions in cookbook names + # :versioned_cookbooks:: whether to include versions in cookbook names def initialize(child_paths, root_paths=[], chef_config=Chef::Config) super("", nil) @child_paths = child_paths diff --git a/lib/chef/chef_fs/file_system/chef_server_root_dir.rb b/lib/chef/chef_fs/file_system/chef_server_root_dir.rb index 61a224c307..370308ee0a 100644 --- a/lib/chef/chef_fs/file_system/chef_server_root_dir.rb +++ b/lib/chef/chef_fs/file_system/chef_server_root_dir.rb @@ -46,19 +46,24 @@ class Chef # # == Parameters # - # - root_name - a friendly name for the root, for printing--like "remote" or "chef_central". - # - chef_config - a hash with options that look suspiciously like Chef::Config, including the - # following keys: - # - :chef_server_url - the URL to the Chef server or top of the organization - # - :node_name - the username to authenticate to the Chef server with - # - :client_key - the private key for the user for authentication - # - :environment - the environment in which you are presently working - # - :repo_mode - the repository mode, :hosted_everything, :everything or :static. - # This determines the set of subdirectories the Chef server - # will offer up. - # - :versioned_cookbooks - whether or not to include versions in cookbook names - # - options - other options: - # - :cookbook_version - when cookbooks are retrieved, grab this version for them. + # [root_name] + # A friendly name for the root, for printing--like "remote" or "chef_central". + # [chef_config] + # A hash with options that look suspiciously like Chef::Config, including the + # following keys: + # :chef_server_url:: The URL to the Chef server or top of the organization + # :node_name:: The username to authenticate to the Chef server with + # :client_key:: The private key for the user for authentication + # :environment:: The environment in which you are presently working + # :repo_mode:: + # The repository mode, :hosted_everything, :everything or :static. + # This determines the set of subdirectories the Chef server will + # offer up. + # :versioned_cookbooks:: whether or not to include versions in cookbook names + # [options] + # Other options: + # :cookbook_version:: when cookbooks are retrieved, grab this version for them. + # :freeze:: freeze cookbooks on upload # def initialize(root_name, chef_config, options = {}) super("", nil) -- cgit v1.2.1