Skip to content

Commit

Permalink
Make directories clearer
Browse files Browse the repository at this point in the history 
Signed-off-by: Ian Maddaus <[email protected]>
  • Loading branch information
@IanMadd
IanMadd committed Dec 4, 2023
1 parent fd6a0a6 commit 2936934
Show file tree
Hide file tree
Showing 4 changed files with 143 additions and 207 deletions.
114 changes: 54 additions & 60 deletions content/chef_repo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ aliases = ["/chef_repo.html"]
parent = "chef_infra/cookbook_reference"
weight = 15
+++
<!-- markdownlint-disable-file MD033 -->

{{< readfile file="content/reusable/md/chef_repo_description.md" >}}

## Generate the chef-repo
Expand All @@ -28,94 +28,88 @@ chef generate repo REPO_NAME

{{< /note >}}

## Directory Structure
## Directory structure

The chef-repo contains several directories, each with a README file that describes what it is for and how to use that directory when managing systems.
The chef-repo contains several directories, each with a README file that describes what it's for and how to use that directory when managing systems.

The default structure of a new chef-repo is:

```output
```plain
. chef-repo
- cookbooks
- README.md
- example
- attribtes
- default.rb
- recipes
- default.rb
- metadata.rb
- README.md
- data_bags
- example
- example_item.json
- README.md
- policyfiles
- README.md
- .chef-repo.txt
- chefignore
- License
- README.md
├── LICENSE
├── README.md
├── chefignore
├── cookbooks
│ ├── README.md
│ └── example
│ ├── README.md
│ ├── attributes
│ │ ├── README.md
│ │ └── default.rb
│ ├── metadata.rb
│ └── recipes
│ ├── README.md
│ └── default.rb
├── data_bags
│ ├── README.md
│ └── example
│ ├── README.md
│ └── example_item.json
└── policyfiles
└── README.md
```

### cookbooks/

This directory contains the cookbooks that are used to configure systems in the infrastructure which are are downloaded from the [Chef Supermarket](https://supermarket.chef.io/) or created locally. The Chef Infra Client uses cookbooks to configuring the systems in the organization. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data.
### cookbooks

### data_bags/
The `cookbooks` directory contains cookbooks that configure systems in the infrastructure which are are downloaded from the [Chef Supermarket](https://supermarket.chef.io/) or created locally. The Chef Infra Client uses cookbooks to configuring the systems in the organization. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data.

The `data_bags/` directory is used to store all the data bags that exist for an organization. Each sub-directory corresponds to a single data bag on the Chef Infra Server and contains a JSON file corresponding to each data bag item.
### data_bags

### policyfiles/
The `data_bags` directory is used to store all the data bags that exist for an organization. Each sub-directory corresponds to a single data bag on the Chef Infra Server and contains a JSON file corresponding to each data bag item.

The `policyfiles/` directory is used to store Policyfiles in the `.rb` format that define the set of cookbooks and attributes to apply to specific systems managed by the Chef Infra Server.
### policyfiles

## chefignore Files
The `policyfiles` directory is used to store Policyfiles in the `.rb` format that define the set of cookbooks and attributes to apply to specific systems managed by the Chef Infra Server.

The chefignore file is used to tell knife which cookbook files in the chef-repo should be ignored when uploading data to the Chef Infra Server. The type of data that should be ignored includes swap files, version control data, build output data, and so fort. The chefignore file uses the `File.fnmatch` Ruby syntax to define the ignore patterns using `*`, `**`, and `?` wildcards.
### chefignore

- A pattern is relative to the cookbook root
- A pattern may contain relative directory names
- A pattern may match all files in a directory
A `chefignore` file tells knife which cookbook files in the chef-repo it should ignore when uploading data to the Chef Infra Server.
Include swap files, version control data, and build output data in a `chefignore` file.

The chefignore file can be located in any subdirectory of a chef-repo: `/`, `/cookbooks`, `/cookbooks/COOKBOOK_NAME/`, etc. It should contain sections similar to the following:

```none
## section
*ignore_pattern
The `chefignore` file has the following rules:

## section
ignore_pattern*
- Patterns use `*`, `**`, and `?` wildcards to match files and directories as defined by the `File.fnmatch` Ruby method.
- A pattern is relative to the directory it's included in.
- A pattern may contain relative directory names.
- A pattern may match all files in a directory.
- You can add a `chefignore` file to any subdirectory of a chef-repo. For example, `/`, `/cookbooks`, `/cookbooks/COOKBOOK_NAME/`, etc.
- Lines that start with `#` are comments.

## section
**ignore_pattern
Group types of ignored files in sections similar to the following:

## section
ignore_pattern**
## section
?ignore_pattern
```plain
## OS generated files
*ignore_pattern
## section
ignore_pattern?
## Editors
another_ignore_pattern*
```

### Examples

The following example shows how to add entries to the `chefignore` file.
See Ruby's [`File.fnmatch` documentation](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch) for information on creating matching file patterns.

#### Ignore editor swap files
#### Examples

Many text editors leave files behind. To prevent these files from being uploaded to the Chef Infra Server, add an entry to the `chefignore` file.
Many text editors leave files behind. To prevent knife from uploading these files to the Chef Infra Server, add an entry to the `chefignore` file.

For Emacs:
For Emacs backup files:

```none
```plain
*~
```

and for vim:
and for Vim swap files:

```none
```plain
*.sw[a-z]
```

Expand Down
57 changes: 32 additions & 25 deletions content/cookbook_repo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,19 @@ chef generate repo REPO_NAME

The default structure of the cookbooks directory is:

```output
. chef-repo
- cookbooks
- example
- attributes
- default.rb
- recipes
- default.rb
- metadata.rb
- README.rb
```plain
.
└── cookbooks
├── README.md
└── example
├── README.md
├── attributes
│ ├── README.md
│ └── default.rb
├── metadata.rb
└── recipes
├── README.md
└── default.rb
```

## Cookbook Commands
Expand All @@ -65,21 +68,25 @@ The `custom_web` cookbook directory has the structure:

```text
. cookbooks
- custom_web
- recipes
- default.rb
- test
- integration
- default
- default_test.rb
- .gitignore
- CHANGELOG.md
- chefignore
- kitchen.yml
- LICENSE
- metadata.rb
- Policyfile.rb
- README.md
└── custom_web
├── CHANGELOG.md
├── LICENSE
├── Policyfile.rb
├── README.md
├── chefignore
├── compliance
│ ├── README.md
│ ├── inputs
│ ├── profiles
│ └── waivers
├── kitchen.yml
├── metadata.rb
├── recipes
│ └── default.rb
└── test
└── integration
└── default
└── default_test.rb
```

Any unneeded directory components can be left unused or deleted, if
Expand Down
140 changes: 35 additions & 105 deletions content/cookbooks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,100 +27,26 @@ Chef Infra Client runs a recipe only when instructed. When Chef Infra Client run

A cookbook is comprised of recipes and other optional components as files or directories.

<!-- markdownlint-disable MD033 -->

<table>
<colgroup>
<col style="width: 16%" />
<col style="width: 8%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="header">
<th>Component</th>
<th>File/Directory Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="/recipes/">Recipes</a></td>
<td>recipes/</td>
<td>{{< readfile file="content/reusable/md/cookbooks_recipe.md" >}}</td>
</tr>
<tr>
<td><a href="/attributes/">Attributes</a></td>
<td>attributes/</td>
<td>{{< readfile file="content/reusable/md/cookbooks_attribute.md" >}}</td>
</tr>
<tr>
<td><a href="/files/">Files</a></td>
<td>files/</td>
<td>A file distribution is a specific type of resource that tells a cookbook how to distribute files, including by node, by platform, or by file version.</td>
</tr>
<tr>
<td><a href="/libraries/">Libraries</a></td>
<td>libraries/</td>
<td>A library allows the use of arbitrary Ruby code in a cookbook, either as a way to extend the Chef Infra Client language or to implement a new class.</td>
</tr>
<tr>
<td><a href="/custom_resources/">Custom Resources</a></td>
<td>resources/</td>
<td>A custom resource is an abstract approach for defining a set of actions and (for each action) a set of properties and validation parameters.</td>
</tr>
<tr>
<td><a href="/templates/">Templates</a></td>
<td>templates/</td>
<td>A template is a file written in markup language that uses Ruby statements to solve complex configuration scenarios.</td>
</tr>
<tr>
<td><a href="/ohai_custom/">Ohai Plugins</a></td>
<td>ohai/</td>
<td>Custom Ohai plugins can be written to load additional information about your nodes to be used in recipes. This requires Chef Infra Server 12.18.14 or later.</td>
</tr>
<tr>
<td><a href="/config_rb_metadata/">Metadata</a></td>
<td>metadata.rb</td>
<td>This file contains information about the cookbook such as the cookbook name, description, and <a href="/cookbook_versioning/">version</a>.</td>
</tr>
</tbody>
</table>

<!-- markdownlint-enable MD033 -->
| Component | File/Directory Name | Description |
|----------------------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Recipes](/recipes/) | recipes/ | {{< readfile file="content/reusable/md/cookbooks_recipe.md" >}} |
| [Attributes](/attributes/) | attributes/ | {{< readfile file="content/reusable/md/cookbooks_attribute.md" >}} |
| [Files](/files/) | files/ | A file distribution is a specific type of resource that tells a cookbook how to distribute files, including by node, by platform, or by file version. |
| [Libraries](/libraries/) | libraries/ | A library allows the use of arbitrary Ruby code in a cookbook, either as a way to extend the Chef Infra Client language or to implement a new class. |
| [Custom Resources](/custom_resources/) | resources/ | A custom resource is an abstract approach for defining a set of actions and (for each action) a set of properties and validation parameters. |
| [Templates](/templates/) | templates/ | A template is a file written in markup language that uses Ruby statements to solve complex configuration scenarios. |
| [Ohai Plugins](/ohai_custom/) | ohai/ | Custom Ohai plugins can be written to load additional information about your nodes to be used in recipes. This requires Chef Infra Server 12.18.14 or later. |
| [Metadata](/config_rb_metadata/) | metadata.rb | This file contains information about the cookbook such as the cookbook name, description, and version. |

## Community Cookbooks

Chef maintains a large collection of cookbooks. In addition, there are thousands of cookbooks created and maintained by the community:

<!-- markdownlint-disable MD033 -->

<table>
<colgroup>
<col style="width: 25%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="header">
<th>Components</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/chef-cookbooks">Cookbooks Maintained by Chef</a></td>
<td>Chef maintains a collection of cookbooks that are widely used by the community.</td>
</tr>
<tr>
<td><a href="https://github.com/sous-chefs">Cookbooks Maintained by Sous Chefs</a></td>
<td>Sous Chefs is a community organization that collaborates to maintain many of the most used Chef cookbooks.</td>
</tr>
<tr>
<td><a href="https://supermarket.chef.io/cookbooks">Cookbooks Maintained by the Community</a></td>
<td>The community has authored thousands of cookbooks, ranging from niche cookbooks that are used by only a few organizations to popular cookbooks used by almost everyone.</td>
</tr>
</tbody>
</table>

<!-- markdownlint-enable MD033 -->
| Components | Description |
|:------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| [Cookbooks Maintained by Chef](https://github.com/chef-cookbooks) | Chef maintains a collection of cookbooks that are widely used by the community. |
| [Cookbooks Maintained by Sous Chefs](https://github.com/sous-chefs) | Sous Chefs is a community organization that collaborates to maintain many of the most used Chef cookbooks. |
| [Cookbooks Maintained by the Community](https://supermarket.chef.io/cookbooks) | The community has authored thousands of cookbooks, ranging from niche cookbooks that are used by only a few organizations to popular cookbooks used by almost everyone. |

## Generate a Cookbook

Expand All @@ -130,19 +56,23 @@ A cookbook generated with`chef generate cookbook custom_web` creates a cookbook

```text
. cookbooks
- custom_web
- recipes
- default.rb
- test
- integration
- default
- default_test.rb
- .gitignore
- CHANGELOG.md
- chefignore
- kitchen.yml
- LICENSE
- metadata.rb
- Policyfile.rb
- README.md
└── custom_web
├── CHANGELOG.md
├── LICENSE
├── Policyfile.rb
├── README.md
├── chefignore
├── compliance
│ ├── README.md
│ ├── inputs
│ ├── profiles
│ └── waivers
├── kitchen.yml
├── metadata.rb
├── recipes
│ └── default.rb
└── test
└── integration
└── default
└── default_test.rb
```
Loading

0 comments on commit 2936934

Please sign in to comment.