The sous-chefs aws cookbook is a set of resources, not a recipe

A cookbook with no recipes to run

The overview is short and unusual for a Chef cookbook. This cookbook provides custom resources for configuring and managing AWS service offerings from Chef Infra, and it is explicitly a resource-only cookbook. The legacy top-level recipes aws::default and aws::ec2_hints have been removed, and the guidance is to use the public aws_* resources directly from your own cookbooks or roles.

That is a deliberate architectural position. A conventional cookbook ships recipes, and a consumer includes it and lists the recipes in a run list, which means the cookbook decides what happens. A resource-only cookbook ships building blocks, and the consumer decides which ones to declare and with what properties. For infrastructure that has to be shaped per environment, that is the more useful arrangement.

The resources are named after the service they manage, so aws_s3_bucket, aws_iam_role, aws_route53_record and aws_cloudformation_stack are all usable from a recipe in your own cookbook. That also means there is no entry point recipe to include, so a consumer upgrading from an older version has to rewrite how the cookbook is used rather than simply bumping a version number.

What the resource list covers and what it does not

The included resources are listed explicitly, which is rare and useful. CloudFormation stack management is aws_cloudformation_stack, CloudWatch is aws_cloudwatch, and instance monitoring is aws_instance_monitoring. Storage and compute come as aws_dynamodb_table, aws_ebs_volume, aws_elastic_ip and aws_secondary_ip. Instances get aws_instance_role and aws_instance_term_protection.

The identity resources are the biggest group: aws_iam_user, aws_iam_group, aws_iam_policy and aws_iam_role. Around them sit aws_elastic_lb for load balancers, aws_kinesis_stream, aws_resource_tag, aws_route53_record and aws_route53_zone for DNS, aws_s3_file and aws_s3_bucket, aws_security_group, aws_ssm_parameter_store for the parameter store, and aws_autoscaling.

The readme is also clear about the boundary. Some AWS resources are not supported because other cookbooks cover them, with aws_security named as an example. That is worth checking before you commit, because a half covered service set means a cookbook dependency graph that is not obvious from the resource names alone.

The repository layout matches a resource-first cookbook. The resources/ directory holds the resource definitions, libraries/ holds helper code, documentation/ holds the per-resource documentation, and metadata.rb describes the cookbook to Chef.

Credentials come from three places, and STS was added

The credentials section describes three ways for the node to authenticate. You can set the credentials explicitly when using the resources, you can use the credentials in the ~/.aws/credentials file, or you can let the resource pick up credentials from the IAM role assigned to the instance. The readme adds that new resources can now assume an STS role, with support for MFA as well.

The local credentials file looks like this:

[default]
aws_access_key_id = ACCESS_KEY_ID
aws_secret_access_key = ACCESS_KEY

and the file also accepts other profiles if they are supplied through the AWS_PROFILE environment variable. That detail matters in a CI runner or a jump host, where several roles may exist and the default profile is not the one you want.

The instance role path is the one to prefer. If your instance has an IAM role, the credentials are resolved automatically by the cookbook using the Amazon instance metadata API, and you can then omit the authentication properties when calling the resource. The readme is careful to add that the instance role must carry the required policies, and it gives a sample policy for EBS volume management as an example of how narrow that permission set can be.

Credentials in a databag and how to load them

For explicit credentials the readme recommends storing them in an encrypted databag and loading them in the recipe where the resources are used. The example data bag is:

% knife data bag show aws main
{
  "id": "main",
  "aws_access_key_id": "YOUR_ACCESS_KEY",
  "aws_secret_access_key": "YOUR_SECRET_ACCESS_KEY",
  "aws_session_token": "YOUR_SESSION_TOKEN"
}

and it is loaded into a recipe with a single call:

aws = data_bag_item('aws', 'main')

after which the values are read from the item:

aws['aws_access_key_id']
aws['aws_secret_access_key']
aws['aws_session_token']

The session token field is the one people often forget. Any temporary credential set, which is what an STS session produces, needs the token alongside the key and the secret, and a resource configured with only two of the three fields fails in a way that looks like an authentication problem rather than a missing property.

The recommendation is also the one the security section asks for. Passing a separate set of credentials to these resources, rather than reusing the node's own IAM credentials, means a compromise of the Chef run is not automatically a compromise of everything the node can do.

The cookbook warns you about itself

There is a section of the readme headed Important - Security Implications, and it is blunt. It asks you to review any and all security implications of using these resources, and states that the cookbook presents resources which could easily be poorly implemented, abused or exploited.

Three reasons are given. The resources have the ability to perform destructive actions, with delete operations as the example. They manage sensitive resources, with IAM and the parameter store named. And they require IAM keys which could be compromised.

The recommendations follow. Do not use IAM credentials of the node, pass a separate set of credentials to these resources instead. Use IAM to restrict credentials to only the actions required, implementing conditions where necessary and following least privilege principles. Follow AWS best practices for managing credentials. And then the sentence that matters most for a decision like this one: review your cookbook implementation, as cloudformation or alternative tooling may be a better fit for managing AWS infrastructure as code.

A cookbook that tells you it may be the wrong tool is unusual, and it is the most useful paragraph in the readme. Chef converges a node, which is a good model for configuring machines and a mediocre model for managing cloud resources that other people and services also mutate.

How the cookbook is tested

The testing section describes a fairly conventional modern cookbook pipeline. The standard CI runs cookstyle, which is the Chef style linter, then chef exec rspec with documentation format, and then the local Dokken backed default suite. Dokken is the container based test harness that lets Kitchen run Chef Infra inside lightweight containers instead of on virtual machines.

Live AWS acceptance coverage is handled separately. It is split into grouped suites in kitchen.live.yml and a manually triggered GitHub workflow backed by repository secrets. The distinction between the default suite and the live suite is the important one. The default suite can run on every change without touching an AWS account, while anything that actually creates infrastructure requires credentials and is triggered by hand, which is the right way to handle it.

The requirements section adds the constraints. The cookbook is tested and supported in CI on Ubuntu 24.04, it needs Chef 15.3 or later, and it has no cookbook dependencies. The repository carries several Kitchen configuration files, kitchen.yml, kitchen.dokken.yml, kitchen.exec.yml, kitchen.live.yml and kitchen.global.yml, alongside a spec/ directory for the unit tests and a test/ directory for integration tests. There is also a LIMITATIONS.md file at the top level, which is worth reading before you rely on a specific resource.

Maintained by a community, released with automation

The cookbook is maintained by the Sous Chefs, described as a community of Chef cookbook maintainers working together to maintain important cookbooks. There is a link to sous-chefs.org and to a channel on the Chef Community Slack for questions. The repository also carries an OpenCollective badge for backers and sponsors.

The tooling in the tree shows a project with its release process automated. There is a .release-please-manifest.json and a release-please-config.json, which is the release-please tool driving version bumps and changelog entries, and a Dangerfile for pull request checks. renovate.json is there for dependency updates, .overcommit.yml runs checks on commit, and .rubocop.yml and .yamllint handle the Ruby and YAML linting. The CHANGELOG.md is the generated history.

The licence is Apache-2.0, with the text in the LICENSE file at the top of the repository. That is a permissive grant with an explicit patent clause and no copyleft obligation on the cookbooks that use it.

The releases are recent and in a steady line: v9.3.2 on 2026-04-21, v9.3.1 on 2026-04-16 and v9.3.0 on 2025-10-15, with the last push on 2026-10-19 and the repository not archived. A major version number well past nine on a resource-only cookbook tells you the API has been revised many times, so the upgrade path between major versions is where the reading is needed.

Editorial conclusion

Adopt the sous-chefs aws cookbook if you already run Chef Infra and want AWS resources managed as Chef resources with idempotent converge rather than as imperative scripts. Skip it if your infrastructure is defined with CloudFormation or Terraform, since the readme itself says other tooling may be a better fit, and think twice if you would be handing it long-lived AWS keys. Before you use it, read LIMITATIONS.md and the security section, prefer the instance role or STS with MFA over static keys, and confirm your Chef version is 15.3 or later, which is the stated minimum.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. sous-chefs/aws on GitHub