Configure a Project through config.json (Chef Automate)¶
The config.json
file is located at the root of the .delivery
folder that is located within a project managed by Chef Automate and configures that project to publish to a Chef Automate pipeline.
Structure¶
The structure of the config.json
file is similar to:
{
"version": "2",
"build_cookbook": {
"name": "build-cookbook",
"path": ".delivery/build-cookbook"
},
"build_nodes": {
"default" : ["name:name_of_builder"]
},
"skip_phases": [
"quality",
"security"
],
"delivery-truck":{
"publish": {
"github": "chef/chef-web-docs"
}
}
}
Configuration Settings¶
The behavior of pipeline phases can be customized using the project’s config.json
file. Each config.json
file has a set of required settings as well as optional settings that can be set, such as which build nodes to use for specific phases, whether to skip certain phases, and so on. The basic settings are defined below; however, additional settings, such as which linting rules to follow, can also be added. See the delivery-truck readme for examples on how to add custom settings.
build_cookbook
Required
The
build_cookbook
setting specifies the location of thebuild-cookbook
used by this project. Abuild-cookbook
may be fetched from five locations:- A local directory within the project
- A git repository
- A Chef Supermarket instance (public or private)
- A Chef server
- A Chef Automate server
build_nodes
Optional
The
build_nodes
setting specifies which build nodes to use for specific phases in the Chef Automate pipeline. The build node may be defined as well as queried via wildcard search.Note
This setting should only be used with build nodes that use the previous push job-based dispatch system. Use the
job_dispatch
setting when using the new ssh-based job dispatch system.delivery-truck
Optional
The
delivery-truck
setting specifies configurations for specific phases of the Chef Automate pipeline:"delivery-truck": { "lint": { "foodcritic": { "only_rules": ["FC002"] } } "publish": { "chef_server": "true" "github": "chef/chef-web-docs" "git": "ssh://git@stash:2222/<project-name>/<repo-name>" "supermarket": "https://supermarket.chef.io", "supermarket-custom-credentials": "true" } ... <more_phases> ... }
dependencies
Optional
The
dependencies
setting specifies run-time dependencies on which the current project depends. These dependency associations affect how projects are promoted through the Union, Rehearsal, and Delivered stages. Dependencies may be defined in the following ways:"project_name"
"project_name:pipeline_name"
"org_name/project_name"
"org_name/project_name:pipeline_name"
If only a project name is provided, the master pipeline for that project is the dependency.
job_dispatch
Optional
The
job_dispatch
setting is needed to use the improved SSH job dispatch system. If you use this setting, you must remove anybuild_nodes
settings from your configuration file."version"
Set the value to “v2” if you wish to use runners and the new job dispatch system:{ ... "job_dispatch": { "version": "v2" ... }
Note
If you omit this setting or set it to “v1”, the previous job dispatch system using push jobs 1.x will be used instead.
"filters"
Similar to the former Chef push jobs-based dispatch system, you can set a variety of filters. Filters control which runners can run a job for a Chef Automate project. You can set filters for the entire project as well as specific filters per phase. You can also specify a matrix of filters to a run phase job repeatedly on multiple platform configurations.The values you can filter on are
os
,platform
,platform_family
, andplatform_version
. If you omit a value, job dispatch will not filter on it.Using a default filter
If you wish to use a default filter for the entire project, you need to set the “default” tag. For example, if you wanted your project phase jobs to be executed on only ubuntu and centos platforms, you could write:
{ ... "job_dispatch": { "version": "v2", "filters" : { "default" : { "os" : ["linux"], "platform" : ["ubuntu", "centos"] } } ... }
Using a phase filter
Phase filters are filters that can be set per phase. They override a default filter for that phase if a default is set. You can specify a phase filter without setting a default. For example, to run the project’s deploy phase specifically on Fedora 6 based systems that overrides a default of Windows, you could write:
{ ... "job_dispatch": { "version": "v2", "filters" : { "default" : { "os" : ["windows"] } "unit" : { "platform_family" : ["fedora"], "platform_version" : ["6"] } } ... }
Using a matrix phase filter
You can set up a matrix of sub-jobs to run a phase on multiple platform configurations. This is itself a phase filter, overriding the default filter but running the phase job repeatedly on multiple runners. Matrix filters are only for phase filters and not the default filter.
For example, if you want to unit test your project across multiple versions of Ubuntu, you could write something like:
{ ... "job_dispatch": { "version": "v2", "filters" : { "unit" : [ { "platform_family" : ["ubuntu"], "platform_version" : ["12.04"] }, { "platform_family" : ["ubuntu"], "platform_version" : ["14.04"] }, { "platform_family" : ["ubuntu"], "platform_version" : ["16.04"] } ] } ... }
skip_phases
Optional
The
skip_phases
setting specifies which phases are skipped by Chef Automate during the execution of a change through the pipeline. If a phase is defined as skipped, this applies to all stages in the pipeline.Currently, the
functional.rb
,quality.rb
,security.rb
, andsmoke.rb
recipes are blank by default and should be set to skipped in theconfig.json
file:"skip_phases": [ "functional", "quality", "security", "smoke" ]
version
Required
The
version
setting specifies the version of the configuration that the Chef Automate server must user. The current default value is2
,
Note
delivery-truck
is a cookbook for Chef Automate that should be a dependency of every recipe in a build-cookbook
, which is effectively a project-specific wrapper cookbook for the delivery-truck
cookbook. The delivery-truck
cookbook defines a set of recipes that correspond to the phases and stages in the Chef Automate pipeline and help ensure good default build-cookbook
behavior. Chef recommends including the delivery-truck
cookbook in all recipes in a build-cookbook
.
Phase Settings¶
The individual phases of Chef Automate may be configured, grouped under the delivery-truck
configuration setting by phase.
publish¶
The publish
phase configuration settings specify the location(s) to which cookbooks are published.
Chef Server¶
If the config.json
file specifies the following cookbooks are published to the Chef server that is part of this Chef Automate configuration:
"delivery-truck":{
"publish": {
"chef_server": "true"
}
}
git¶
If the config.json
file specifies the following cookbooks are published to a git repository located on an open source git server:
"delivery-truck":{
"publish": {
"git": "ssh://git@stash:2222/<project-name>/<repo-name>"
}
}
This publishing option requires the git
deploy key for that repository to be available from a data bag on the Chef server that is part of this Chef Automate configuration.
GitHub¶
If the config.json
file specifies the following cookbooks are published to a GitHub repository:
"delivery-truck":{
"publish": {
"github": "chef/chef-web-docs"
}
}
where "chef/chef-web-docs"
represents the organization/repository to which the build-cookbook
belongs.
This publishing option requires the github
deploy key for that repository to be available from a data bag on the Chef server that is part of this Chef Automate configuration.
Supermarket¶
Publish cookbooks to the public Chef Supermarket:
If the config.json
file specifies the following cookbooks are published to the public Chef Supermarket:
"delivery-truck":{
"publish": {
"supermarket": "https://supermarket.chef.io"
}
}
Publish cookbooks to a private Chef Supermarket:
"delivery-truck":{
"publish": {
"supermarket": "https://private-supermarket.example.com"
}
}
Publish cookbooks to Chef Supermarket, but with custom credentials:
"delivery-truck":{
"publish": {
"supermarket": "https://supermarket.chef.io",
"supermarket-custom-credentials": "true"
}
}
This publish
option requires the supermarket_user
and supermarket_key
credentials to be available from the
delivery-secrets
data bag on the Chef server that is part of this Chef Automate configuration. For more information on the delivery-secrets
data bag,
see Handling Secrets in the delivery-sugar
cookbook README file.
Note
To enable Chef Automate to upload cookbooks to a private Supermarket, you have to manually log into the Supermarket server with the delivery
user, and when it prompts you to enable the user for Supermarket, enter yes
. Also, you must copy the Supermarket certificate file to /etc/delivery/supermarket.crt
on the Chef Automate server.
Multiple Locations¶
If the config.json
file may specify some or all of the publish options together as a single block:
"delivery-truck":{
"publish": {
"chef_server": "true"
"github": "chef/chef-web-docs"
"git": "ssh://git@stash:2222/<project-name>/<repo-name>"
"supermarket": "https://supermarket.chef.io",
"supermarket-custom-credentials": "true"
}
}
or:
"delivery-truck":{
"publish": {
"chef_server": "true"
"supermarket": "https://supermarket.chef.io"
}
}
Examples¶
The following examples show different ways to specify settings and pipeline behaviors in the config.json
file.
build-cookbook Locations¶
The following examples show how to specify the location of the build-cookbook
.
A local directory
"build_cookbook": {
"name": "build-cookbook",
"path": ".delivery/build-cookbook"
}
A git source
"build_cookbook": {
"name" : "delivery-truck",
"git" : "https://github.com/chef-cookbooks/delivery-truck.git",
"branch": "master"
}
A public Supermarket (https://supermarket.chef.io)
"build_cookbook": {
"name": "delivery-truck",
"supermarket": "true"
}
A private Supermarket
"build_cookbook": {
"name": "delivery-truck",
"supermarket": "true",
"site": "https://private-supermarket.example.com"
}
A Chef server
"build_cookbook": {
"name": "delivery-truck",
"server": "true"
}
A Chef Automate server
"build_cookbook": {
"name": "delivery-truck",
"enterprise": "chef",
"organization": "chef-cookbooks"
}
Build Nodes and Phases¶
The following example shows how to specify build nodes to be used for specific phases.
"build_nodes": {
"provision": ["name:builder-*-2.delivery.chef.co AND platform_version:14.04"],
"deploy": ["name:builder-*-2.delivery.chef.co AND platform_version:14.04"],
"functional": ["name:builder* AND platform_version:14.04 NOT name:builder-*-2.delivery.chef.co"]
}
Run-time Dependencies¶
The following example shows a run-time dependency against the master branch of a project named BackendAPI
:
{
"version": "2",
"build_cookbook": {
"name": "build-cookbook",
"path": ".delivery/build-cookbook"
},
"skip_phases": [],
"dependencies": ["BackendAPI"]
}
Stages and Platforms¶
The "build_nodes"
section may also specify build nodes by stages and/or platform:
{
...
"build_nodes": {
"default" : ["name:builder"],
"unit" : ["name:builder AND platform_family:platform"],
"..." : ["name:builder AND platform_family:platform"]
}
...
}
For example:
{
...
"build_nodes": {
"default" : ["name:builder*.foo.com"],
"unit" : ["name:builder*.foo.com AND platform_family:debian"],
"syntax" : ["name:builder*.foo.com AND platform_family:rhel"],
"publish" : ["name:builder*.foo.com AND platform_family:debian", "name:builder*.foo.com AND platform_family:rhel"]
}
...
}
Test Patterns¶
The following example shows how to configure Chef Automate to ignore and/or run certain Foodcritic rules, and to exclude running tests that are located in the specified cookbook directories:
{
"version": "2",
"build_cookbook": {
"name": "delivery-truck",
"git": "https://github.com/chef-cookbooks/delivery-truck.git"
},
"delivery-truck": {
"lint": {
"foodcritic": {
"ignore_rules": ["FC009", "FC057", "FC058"],
"only_rules": ["FC002"],
"excludes": ["spec", "test"],
"fail_tags": ["any"]
}
}
}
}
where:
ignore_rules
is set to ignore Foodcritic rulesFC009
,FC057
,FC058
only_rules
is set to run only Foodcritic ruleFC002
; omit this setting to specify all rules not specified byignore_rules
excludes
prevents Foodcritic rules from running if they are present in a cookbook’s/spec
and/or/test
directoriesfail_tags
states which rules should cause the run to fail; omit this setting to specifycorrectness
Foodcritic, excludes¶
If the config.json
file specifies:
"delivery-truck": {
"lint": {
"foodcritic": {
"ignore_rules": ["RULE", "RULE", ...],
"only_rules": ["RULE", "RULE", ...],
"excludes": ["spec", "test"]
}
}
}
then Foodcritic rules are not run against tests that are located in the specified directories, in this case the /spec
and /test
directories.
Foodcritic, ignore_rules¶
If the config.json
file specifies:
"delivery-truck": {
"lint": {
"foodcritic": {
"ignore_rules": ["FC009", "FC057", "FC058"],
"excludes": ["DIRECTORY", "DIRECTORY", ...]
}
}
}
then all Foodcritic rules except FC009
, FC057
, and FC058
rules are run.
Foodcritic, only_rules¶
If the config.json
file specifies:
"delivery-truck": {
"lint": {
"foodcritic": {
"only_rules": ["FC002"],
"excludes": ["DIRECTORY", "DIRECTORY", ...]
}
}
}
then only the FC002
Foodcritic rules is run.