The yum_repository resource provider is not documented.

chef-web-docs/includes_resources/includes_resource_dsc_resource_requirements.rst Should include a note that dsc_resource can only use binary or script resources. Composite DSC resources are not supported by dsc_resource. See - https://discourse.chef.io/t/dsc-resource-will-not-work-with-composite-resources/8443/2?u=steven_murawski

https://github.com/chef/inspec/blob/master/docs/matchers.rst

Issue:
1 - Installation should not exclusively rely on community cookbook(s), custom data_bag, etc.. and it should not be a 'black box'.
2 - a user interested in understanding the Supermarket setup process is tasked with reverse engineering a community cookbook to understand what's happening.

Expectation:
Supermarket installation should be fully documented, and any user should be able to setup Supermarket by hand (in a similar fashion to chef-server, analytics, etc..). A link to community resource which aids in the task can be provided as a secondary route for installation.

Reference:
https://docs.chef.io/install_supermarket.html

The functionality is out there, but it doesnt seem to be documented.
Not sure on the place place, perhaps start with here:
https://docs.chef.io/chef_license.html
and
https://docs.chef.io/api_chef_server.html

knife raw license -s https://localhost/ -c /etc/opscode/pivotal.rb

# knife raw license -s https://localhost/ -c /etc/opscode/pivotal.rb
{
  "limit_exceeded": true,
  "node_license": 25,
  "node_count": 28124,
  "upgrade_url": "http://www.getchef.com/contact/on-premises-simple"
}

https://docs.chef.io/resource_dsc_resource.html

The line:

message << "Chef run failed on #{node.name}\n"

Should probably be:

message << "Chef run failed on #{node_name}\n"

as defined in your method definition.

While the About Policyfile page at https://docs.chef.io/policy.html seems to cover the latest implementation, the Policyfile.rb page at https://docs.chef.io/config_rb_policyfile.html is currently rather incomplete and thus misleading (unfortunately the first result in https://docs.chef.io/search.html?q=Policyfile).

Would be helpful to add a link to the "About Policyfile" doc page at the recently updated https://github.com/chef/chef-dk/blob/master/POLICYFILE_README.md since this is still the main "landing page" (https://www.google.de/search?q=chefdk%20policyfile)

I just found an option in the chef code [1] about an option "rubygems_url" which if used for installing gems defined in the metadata.rb.
I could not find any documentation about this option but I think its quite handy.

[1] https://github.com/chef/chef/blob/master/lib/chef/cookbook/gem_installer.rb

Link to be added (or duplicated):
https://github.com/chef/chef-rfc/blob/master/rfc021-platform-support-policy.md

Page in question:
https://docs.chef.io/chef_system_requirements.html

Reason:
that RFC is the best authoritative source of supported platforms, however it's not referenced anywhere in our official docs, which leads customers to infer supported platforms from the download page, or other non-authoritative sources.

The apt_repository resource introduced in Chef 12.9 (chef/chef#4782) is missing in the documentation.

The Chef Server API docs page shows the use of the private_key parameter in the /clients/NAME and /users/NAME PUT endpoints. The use of the private_key parameter has been removed and will throw a HTTP 400 error when used.

https://docs.chef.io/api_chef_server.html

From the Release Notes:

Including any of public_key, private_key, or create_key in PUT requests to 
client/users will cause a 400 response with detailed message.

https://github.com/chef/chef-server/blob/master/PRIOR_RELEASE_NOTES.md#api-changes-and-additions-2

Rendered at https://docs.chef.io/server_orgs.html#default-groups

I believe these:

The admins group is assigned permissions to the following groups by default:

The billing admins group is assigned permissions to the following group by default:

Should match the wording in these that follow those:

The clients group is assigned the following permissions by default to objects on the Chef server:

The users group is assigned the following permissions by default to objects on the Chef server:

@jamescott , It looks like some wires are crossed.

resource_osx_profile is completely different from resource_launchd.

It looks like some terminology and actions from osx_profile: https://docs.chef.io/release/12-7/resource_osx_profile.html

Ended up in the documentation for resource_launchd:

https://docs.chef.io/release/12-8/resource_launchd.html

A launchd is not a configuration profile. It is a completely different resource. The way it is referred to in this PR is correct ( "...resource to manage launchd daemons / agents") but in the documentation you linked, it says "A launchd resource to manage configuration profiles (.mobileconfig files) on the Mac OS X platform", which is not correct.

For instance:

resource_osx_profile is a .mobileconfig file

resource_launchd is a .plist file

A resource_launchd is a service like cron or upstart. It is not a configuration profile at all. It is a service.

Thanks for getting the docs updated! Let us know if any further clarification is needed.

As a customer, I read docs.chef.io for documentation, so I'm thoroughly confused when our docs don't contain the search term "partial search"

It turns out, the term "partial search" is equivalent to the term "filter result".

The only place this important fact is documented is outside of the docs, in https://www.chef.io/blog/2014/12/05/release-chef-client-12-0-0/ at the section "Built in partial search for knife and recipes".

1. It would be helpful if the explanation from the above link were included in the official docs. It's preferable that anywhere "filter result" is mentioned, that that site in the docs also mention "partial search". Chef spent a year or so acculturating people to the latter term. The most important place that equivalency could be made is probably in https://docs.chef.io/chef_search.html#filter-search-results , so that it is found in searching.

2. Additionally, verbiage should be added to the introduction for this section to make it apparent that this form of searching would occur as part of a recipe.

   Use :filter_result in a recipe as part of a search query against the Chef server to return data in the form of the specified Hash. This usage with the filter_result option is also known as partial search
   

3. The following is a working example of a partial search/filter results with knife 12.7.2 against Hosted Chef, which could be included above the previous link, in the section with the other knife search examples

   knife search node "platform:ubuntu" --filter-result "c_version=languages.c.gcc.version, ruby_version=languages.ruby.version"
   

I spent several hours today trying to wrap my head around Handlers and get failure event notification over email working. There are a couple of examples out there, but they all assume a rather high level of understanding about things, especially around where certain configurations should go (in which file, etc).

I got it working with chef_handler, but I basically pieced together stuff from the chef handler documentation, as well as various other places on the internet.

A fully functional, detail walkthrough of how to configure email using chef_handler would probabaly be extremely useful for a lot of people, and especially n00bs to Chef like myself. I'm gonna document my configuration in a Gist and I'll link to it here if it's useful.

Hi all! The documentation suggests the following command to be used for unsharing a specific version of a cookbook shared on the Chef Supermarket:

$ knife cookbook site unshare COOKBOOK_NAME/version/VERSION

The request keeps failing with the following message:

Do you really want to unshare all versions of the cookbook dynatrace/version/6.3.0? (Y/N) Y
ERROR: Server returned error 500 for https://supermarket.chef.io/api/v1/cookbooks/dynatrace/version/..., retrying 1/5 in 3s
ERROR: Server returned error 500 for https://supermarket.chef.io/api/v1/cookbooks/dynatrace/version/..., retrying 2/5 in 6s
...

The documentation has to be changed as follows to make unsharing work:

$ knife cookbook site unshare COOKBOOK_NAME/versions/VERSION

The instructions in https://docs.chef.io/community_contributions.html#set-up-repo don't actually work, as they say to add a remote called 'opscode' but later reference it as 'chef' (e.g. compare step 5 and step 7).

See https://github.com/chef/chef-server/blob/master/src/oc_erchef/apps/oc_chef_wm/src/oc_chef_wm_org_associations.erl#L8-L15

https://github.com/chef/inspec/blob/master/docs/ruby_usage.rst

I believe this to be a typo:
https://docs.chef.io/resource_ksh.html
"A ksh resource block executes scripts using csh:"

chef_repo.html instructs to use the github repo here https://github.com/chef/chef-repo, however that repo is deprecated.

The repository says you should use chef generate repo instead.

https://github.com/chef/chef-web-docs/blob/master/includes_server_ha/includes_server_ha_aws.rst

Machines are stored as Amazon Elastic Block Store (EBS) volumes. A passive node monitors the availabilty of the active node, and will take over if required.

Does that say what was meant? I'm not sure. Rendered w/ image above it: https://docs.chef.io/server_high_availability.html

The first sentence confuses me altogether :). I think what it's supposed to say is something like, "Backend servers make use of a single Amazon EBS volume." ?

The second sentence could maybe have minor tweaking to be "The passive back-end node monitors the availabilty of the active back-end node, and will take over if required."

or, more important, no release notes. Would be good to sync, though we should probably sort out how we ended up so far behind.

Doc url: https://docs.chef.io/install_analytics.html

Issue: Below step only works in combined mode and presently explodes, leading users to believe something's gone wrong with their Analytics install. There is a pending code fix, however until it's done, best remove it from the doc to avoid extra confusion.

Verify the installation on the Chef Analytics server:
$ opscode-analytics-ctl test

Internal Refs:
https://getchef.zendesk.com/agent/tickets/9620
https://chefio.atlassian.net/browse/TRI-156

I followed the README steps to setup and test changes I get the error:

chef-web-docs/chef_master/source/debug.rst:28: WARNING: Could not lex literal_block as "ruby". Highlighting skipped.

for master and for the 12-13 releases when I use the command "make master" or "make 12-13". Any suggestions for what I might be missing?

thanks,
Mark

URL: https://docs.chef.io/install_delivery_aws.html

Beneath the Configure Delivery section is the subsection for Add Users (below). It states, "...use the follow procedure to create a new user...", however, that procedure is not included.

Add Users¶
The default admin account should not be used after Delivery is installed. Instead, use the following procedure to create a new user for yourself, then log out as admin and log back in as the user you created.

It looks like some things were left out when compared to what's in the chef repo. One of the significant potentially breaking changes is "Chef::REST is no longer globally required, so if your code uses Chef::REST, you must ensure that you require it correctly".

It would be nice to have that and others copied into the docs.chef.io Chef Client 12.7 release notes.

https://github.com/chef/chef/blob/12.7.2/RELEASE_NOTES.md#chefrest

https://github.com/chef-cookbooks/mysql/blob/master/.kitchen.cloud.yml is not a thing

From README.MD, Building Docs:

## Building Docs

There's a `Makefile` in the root of the repo, that should have the majority of the tasks you'll ever need.

Run:

    make release

This will build *all* the documentation into HTML, and place it inside `./build/chef/`.
Open `./build/chef/index.html` to view the rendered files locally.

But the target does not exists in the Makefile (master branch) and will cause an error when running it.

[genadi@localhost chef-web-docs]# make release
make: *** No rule to make target `release'.  Stop.

Unless I am misreading the source, there is no Chef::Provider::Service::Init::Debian, only Chef::Provider::Service::Debian. Am I incorrect?

On this page: https://docs.chef.io/config_rb_policyfile.html

default_source :supermarket
default_source :supermarket, "https://supermarket.example" do |s|
  s.preferred_source_for "chef-client"
end

There are several references to a method preferred_source_for but that method doesn't exist. The correct method name is preferred_for

There is no documentation how chef client interprets when manage_symlink_source is set to false.

https://github.com/chef/chef-web-docs/blob/master/includes_dsl_recipe/includes_dsl_recipe_method_edit_resource.rst

Following is syntactically invalid:

edit_resource(:template, '/x/y.txy') do
  cookbook_name: cookbook_name
end

syntax error, unexpected ':', expecting keyword_end

Wasn't sure if this was the right place, but the release notes here:

https://docs.chef.io/release/12-7/release_notes.html

have a defect from a previous change (...s (.profile files) on the Mac OS X platform.). it should be (.mobileconfig) files.

Let me know if you need other info.

Thanks!

Nate

https://docs.chef.io/resource_windows_package.html does not include information about 'version' attribute.

In order to use helper methods in a custom_resource action_class seems to be the way to go. Action_class is very hard to find in the documentation though. The best doc I can find about using action_class is contained in this comment "Refer to the notes about custom resources if you’re curious about other approaches that use the older styles." Most people don't look there when they are working on a 12.5 style custom resource because of the "older styles" comment.

I'd like to see something inserted into the custom_resources documentation about action_class.

Thanks,
Mark

https://docs.chef.io/search.html?q=containers
https://www.chef.io/solutions/containers/

I have had the opportunity to teach and discuss Chef to many new users over the past few years. A concept that is hard for users that are not yet accustomed to ruby is the ~>. More over this is a tough set of characters to google search. By using the term twiddle-wakka you give the user something to sync google's teeth into.

While the documentation at https://docs.chef.io/config_rb_metadata.html is currently likely enough to explain:

A range of chef-client versions that are supported by this cookbook.

For example, to match any 12.x version of the chef-client, but not 11.x or 13.x:
chef_version "~> 12"

Providing the word to google and find out more and a link to http://guides.rubygems.org/patterns/#declaring-dependencies will likely give the more curious an avenue to learn more and understand the history.

The documentation for the clients/client/keys incorrectly uses client/client/keys as the url.

Searching for "client/" on the Chef Server API page will show all the incorrect instances.

https://docs.chef.io/api_chef_server.html

In addition, the raml-docs in the chef-server repo are incorrect. Lines 17 and 20 in the keys.yaml file:

https://github.com/chef/chef-server/blob/bb28b489960c8fae6ac061bf2dab5800142b22a3/src/oc_erchef/raml-docs/organizations/clients/keys.yaml

-f FILE_NAME, --file FILE_NAME
The name of an Ohai plugin against which Ohai will run. (Only one Ohai plugin may be specified when using this option.)

-f doesn't work and isn't listed by --help

The knife supermarket docs say in a warning at the top:

Only use knife supermarket if you are using a Chef 12.12 or earlier. If you are using Chef 12.13 or later, you should use the knife cookbook site commands.

However, the knife cookbook site docs say nothing about connecting to a private supermarket.

Turns out, however, you an actually set the knife[:supermarket_site] attribute in your knife.rb file and get your knife cookbook site commands to interact with your private supermarket, but I see that documented nowhere besides the knife supermarket and supermarket pages.

So I propose that the knife cookbook site docs need updated to include this config value, or include it in the knife.rb page. Thoughts?

23a40d7 made lots of things in to redirects inappropriately. People are still using those products even if new ones are available so the docs should still be there.

https://github.com/chef/chef-web-docs/blob/master/includes_server_ha/includes_server_ha_drbd_scenario_1and2.rst

When the acting backup server fails, ...

Trivial, but, in the context of the rendered page at https://docs.chef.io/server_high_availability.html, I don't believe those are the words intended. Maybe "When the active back-end server fails," ?

The Chef Server API docs has the admin parameter listed as a usable parameter on the /clients POST and /clients/NAME PUT endpoints.

https://docs.chef.io/api_chef_server.html

The Release Notes for Chef Server 12.1.0 say that:

In client creation and update, the last remnants of the admin flag have been 
removed. It was previously partially supported in that we would capture and 
update the value, but the value was unused in the system. If submitted in 
POST/PUT of a client or user, it is ignored.

https://github.com/chef/chef-server/blob/master/PRIOR_RELEASE_NOTES.md#api-changes-and-additions-2

Currently we have

. { iwr -useb https://omnitruck.chef.io/install.ps1 } | iex; install

This will install Chef Client.

For Delivery CLI we can use

. { iwr -useb https://omnitruck.chef.io/install.ps1 } | iex; install -project delivery-cli -architecture x86_64

Thanks for the overall excellent core docs! Just wanted to mention a small thing that threw me off today:

In the current docs for resource_directory properties, it says the following:

recursive
Ruby Types: TrueClass, FalseClass

Create or delete parent directories recursively. For the owner, group, and mode properties, the value of this attribute applies only to the leaf directory. Default value: false.

When using action :create , the above applies, and parent directories are created recursively. When using action :delete , it deletes child directories and files recursively. This follows POLA - I was expecting rm -rf , but the docs made it sound like the entire hierarchy would get blown away.

The example under "Delete Directory" looks correct, but it doesn't elaborate on this:

directory '/tmp/something' do
  recursive true
  action :delete
end

From the property text, it looks like this would delete /tmp as well as /tmp/something and presumably /tmp/something/a_file.txt .

Maybe I habitually over-think things, but this threw me off until I tried it out in test-kitchen. A sentence in the attribute text or below the example to clarify the different behavior would be super appreciated. Might help other paranoid over-thinkers and careful-readers 😆

Cheers,

The current set of docs for powershell_script : https://docs.chef.io/resource_powershell_script.html
doesn't show the support for sensitive [TrueClass, FalseClass] please update so users that need data such as passwords or other sensitive items not show up in the chef log in plain text.

This is a copy of the issue at the old repo. The examples are still outdated.

https://docs.chef.io/resource_chocolatey_package.html