Habitat Cookbook
Description
This cookbook provides resources for working with Habitat. It is intended that these resources will be included in core Chef at some point in the future, so it is important to note:
- APIs are subject to change
- Habitat is a rapidly changing product, and this cookbook may change rapidly as well
TODOS
- Remove reliance on
toml-rb
gem.
License Note
Habitat requires acceptance of a license before any habitat commands can be run. To accept the Habitat license using this cookbook, the license
parameter can be set to accept
for either the hab_install
or hab_sup
resources as shown in the below examples:
hab_install 'install habitat' do
license 'accept'
end
hab_sup 'default' do
license 'accept'
end
PLEASE NOTE: Without performing one of the above license acceptance steps, all other resources in the habitat cookbook will fail with an error prompting that the license must be accepted.
Requirements
Platforms
- RHEL 6+
- Ubuntu 16.04+
- Debian 9+
- Windows 2016+
Habitat
- Habitat version: 1.6.56+
You can also pin to older versions if desired
This cookbook used to base version number off of the latest stable Habitat release and install a specific version of Habitat based upon the cookbook version. Current behavior is now that the cookbook will install the latest stable release of Habitat on the source Habitat Builder which is contacted by default, but allows for explicit version pinning to be set via cookbook resources.
Chef
- Chef 12.20.3+
Cookbooks
- None
Resources
hab_install
Installs Habitat on the system using the install script.
Actions
install
: Installs Habitat. Does nothing if thehab
binary is found in the default location for the system (/bin/hab
on Linux,/usr/local/bin/hab
on macOS,C:/habitat/hab.exe
on Windows)upgrade
: Installs the latest version of Habitat, does not check if the binary exists
Properties
install_url
: URL to the install script, default is from the habitat repobldr_url
: Optional URL to an alternate Builder (defaults to the public Builder)create_user
: Creates thehab
system user (defaults totrue
)tmp_dir
: Sets TMPDIR environment variable for location to place temp files. (required if/tmp
and/var/tmp
are mountednoexec
)license
: Specifies acceptance of habitat license when set toaccept
(defaults to empty string).hab_version
: Specify the version ofHabitat
you would like to install (defaults to latest)
Examples
# Nameless Installation
hab_install
# Instalaltion specifying a bldr URL
hab_install 'install habitat' do
bldr_url 'http://localhost'
end
# Installtation specifying version and bldr URL
hab_install 'install habitat' do
bldr_url 'http://localhost'
hab_version '1.5.50'
end
hab_package
Install the specified Habitat package from builder. Requires that Habitat is installed
actions
install
: installs the specified packageupgrade
: installs the specified package. If a newer version is available in the configured channel, upgrades to that versionremove
: Will remove packages no longer wanted.
Properties
package_name
: A Habitat package name, must include the origin and package name separated by/
, for example,core/redis
version
: A Habitat version which contains the version and optionally a release separated by/
, for example,3.2.3
or3.2.3/20160920131015
bldr_url
: The habitat builder url where packages will be downloaded from (defaults to public habitat builder)channel
: The release channel to install from (defaults tostable
)auth_token
: Auth token for installing a package from a private organization on builderbinlink
: If habitat should attempt to binlink the package. Acceptable values:true
,false
,:force
. Will faill on binlinking if set totrue
and binary or binlink exists.options
: Pass any additional parameters to the habitat install command.keep_latest
: Ability to uninstall while retaining a specified version (Default is not set.This feature only works in Habitat 1.5.86+
)no_deps
: Remove package but retain dependencies (Default isfalse
)
While it is valid to pass the version and release with a Habitat package as a fully qualified package identifier when using the hab
CLI, they must be specified using the version
property when using this resource. See the examples below.
Examples
hab_package 'core/redis'
hab_package 'core/redis' do
version '3.2.3'
channel 'unstable'
end
hab_package 'core/redis' do
version '3.2.3/20160920131015'
end
hab_package 'core/nginx' do
binlink :force
end
hab_package 'core/nginx' do
options '--binlink'
end
# Remove all
hab_package 'core/nginx'
action :remove
end
# Remove specified
hab_package 'core/nginx/3.2.3'
action :remove
end
# Remove but retain some versions (only available as of Habitat 1.5.86)
hab_package 'core/nginx'
keep_latest '2'
action :remove
end
# Renove but keep dependencies
hab_package 'core/nginx'
no_deps false
action :remove
end
hab_service
Manages a Habitat application service using hab sup
/hab service
. This requires that core/hab-sup
be running as a service. See the hab_sup
resource documentation below for more information about how to set that up with this cookbook.
Note: Applications may run as a specific user. Often with Habitat, the default is hab
, or root
. If the application requires another user, then it should be created with Chef's user
resource.
Actions
:load
: (default action) runshab service load
to load and start the specified application service:unload
: runshab service unload
to unload and stop the specified application service:reload
: runs the:unload
and then:load
actions:start
: runshab service start
to start the specified application service:stop
: runshab service stop
to stop the specified application service:restart
: runs the:stop
and then:start
actions
Properties
The remote_sup property is valid for all actions.
remote_sup
: Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632]remote_sup_http
: Address for remote supervisor http port. Used to pull existing configuration data. If this is invalid, config will be applied on every Chef run.gateway_auth_token
: Auth token for accessing the remote supervisor's http port.
The follow properties are valid for the load
action.
service_name
: name property, the name of the service, must be in the form oforigin/name
loaded
: state property indicating whether the service is loaded in the supervisorrunning
: state property indicating whether the service is running in the supervisorstrategy
: Passes--strategy
with the specified update strategy to the hab command. Defaults to:none
. Other options are:'at-once'
and:rolling
update_condition
: Passes--update-condition
dictating when this service should updated. Defaults tolatest
. Options arelatest
ortrack-channel
Note: This requires a minimum habitat version of 1.5.71latest
: Runs the latest package that can be found in the configured channel and local packages.track-channel
: Always run what is at the head of a given channel. This enables service rollback where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is packages newer than the package at the head of the channel will be automatically uninstalled during a service rollback.
topology
: Passes--topology
with the specified service topology to the hab commandbldr_url
: Passes--url
with the specified Builder URL to the hab command. Depending on the type of Builder you are connecting to, this URL will look different, here are the 3 current types:- Public Builder (default) -
https://bldr.habitat.sh
- On-Prem Builder installed using the Source Install Method -
https://your.bldr.url
- On-Prem Builder installed using the Automate Installer -
https://your.bldr.url/bldr/v1
- Public Builder (default) -
channel
: Passes--channel
with the specified channel to the hab commandbind
: Passes--bind
with the specified services to bind to the hab command. If an array of multiple service binds are specified then a--bind
flag is added for each.binding_mode
: Passes--binding-mode
with the specified binding mode. Defaults to:strict
. Options are:strict
or:relaxed
service_group
: Passes--group
with the specified service group to the hab command
Examples
# install and load nginx
hab_package 'core/nginx'
hab_service 'core/nginx'
hab_service 'core/nginx unload' do
service_name 'core/nginx'
action :unload
end
# pass the strategy and topology options to hab service commands (load by default)
hab_service 'core/redis' do
strategy 'rolling'
topology 'standalone'
end
# Using update_condition
hab_service 'core/redis' do
strategy 'rolling'
update_condition 'track-channel'
topology 'standalone'
end
If the service has it's own user specified that is not the hab
user, don't create the hab
user on install, and instead create the application user with Chef's user
resource
hab_install 'install habitat' do
create_user false
end
user 'acme-apps' do
system true
end
hab_service 'acme/apps'
hab_sup
Runs a Habitat Supervisor for one or more Habitat Services. It is used in conjunction with hab_service
which will manage the services loaded and started within the supervisor.
The run
action handles installing Habitat using the hab_install
resource, ensures that the appropriate versions of the core/hab-sup
and core/hab-launcher
packages are installed using hab_package
, and then drops off the appropriate init system definitions and manages the service.
All event_stream_*
properties are optional, and allow the Habitat Supervisor to display details about it's status and running services via the Chef Automate Applications Dashboard.
Note: Automate has TLS on by default. You will need to follow these instructions to make sure habitat has the proper certificates for event_stram_*
Share the TLS Certificate with Chef Habitat
Actions
run
: starts thehab-sup
service
Properties
bldr_url
: The Builder URL for thehab_package
resource, if neededpermanent_peer
: Only valid for:run
action, passes--permanent-peer
to the hab commandlisten_ctl
: Only valid for:run
action, passes--listen-ctl
with the specified address and port, e.g.,0.0.0.0:9632
, to the hab commandlisten_gossip
: Only valid for:run
action, passes--listen-gossip
with the specified address and port, e.g.,0.0.0.0:9638
, to the hab commandlisten_http
: Only valid for:run
action, passes--listen-http
with the specified address and port, e.g.,0.0.0.0:9631
, to the hab commandorg
: Only valid for:run
action, passes--org
with the specified org name to the hab commandpeer
: Only valid for:run
action, passes--peer
with the specified initial peer to the hab commandring
: Only valid for:run
action, passes--ring
with the specified ring key name to the hab commandauto_update
: Passes--auto-update
. This will set the Habitat supervisor to automatically update itself any time a stable version has been releasedupdate_condition
: Passes--update-condition
dictating when this service should updated. Defaults tolatest
. Options arelatest
ortrack-channel
Note: This requires a minimum habitat version of 1.5.71latest
: Runs the latest package that can be found in the configured channel and local packages.track-channel
: Always run what is at the head of a given channel. This enables service rollback where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is packages newer than the package at the head of the channel will be automatically uninstalled during a service rollback.
hab_channel
: The channel to install Habitat from. Defaults to stableauth_token
: Auth token for accessing a private organization on bldr. This value is templated into the appropriate service file.gateway_auth_token
: Auth token for accessing the supervisor's HTTP gateway. This value is templated into the appropriate service file.license
: Specifies acceptance of habitat license when set toaccept
(defaults to empty string).health_check_interval
: The interval (seconds) on which to run health checks (defaults to 30).event_stream_application
: The name of your application that will be displayed in the Chef Automate Applications Dashboardevent_stream_environment
: The application environment for the supervisor, this is for grouping in the Applications Dashboardevent_stream_site
: Application Dashboard label for the "site" of the application - can be filtered in the dashboardevent_stream_url
:AUTOMATE_HOSTNAME:4222
- the Chef Automate URL with port 4222 specified (can be changed if needed)event_stream_token
: Chef Automate token for sending application event stream dataevent_stream_cert
: WithIntermediary Certificates
or, Automate 2 being set to use TLS with a valid cert, you will need to provideHabitat
with your certificate for communication with Automate to work. Follow these steps!sup_verstion
: Allows you to choose which version of supervisor you would like to install. Defaults tolatest
. (If a version is provided, it will also install that version of habitat if not previously installed)launcher_version
: Allows you to choose which version of launcher to install. Defaults tolatest
service_version
: Allows you to choose which version of the Windows Service to install. Defaults tolatest
keep_latest
: Automatically cleans up old packages. If this flag is enabled, service startup will initiate an uninstall of all previous versions of the associated package. This also applies when a service is restarted due to an update. If a number is passed to this argument, that number of latest versions will be kept. The same logic applies to the Supervisor packagenv:HAB_KEEP_LATEST_PACKAGES=1
(This requires Habitat version1.5.86+
)
Examples
# set up with just the defaults
hab_sup 'default'
hab_sup 'test-options' do
listen_http '0.0.0.0:9999'
listen_gossip '0.0.0.0:9998'
end
# Use with an on-prem Builder
# Access to public builder may not be available
hab_sup 'default' do
bldr_url 'https://bldr.private.net'
end
# Using update_condition
hab_sup 'default' do
bldr_url 'https://bldr.private.net'
hab_channel 'dev'
update_condition 'track-channel'
end
# Provide event_stream_* information
hab_sup 'default' do
license 'accept'
event_stream_application 'myapp'
event_stream_environment 'production'
event_stream_site 'MySite'
event_stream_url 'automate.private.net:4222'
event_stream_token 'myawesomea2clitoken='
event_stream_cert '/hab/cache/ssl/mycert.crt'
end
# Provide specific versions
hab_sup 'default' do
bldr_url 'https://bldr.private.net'
sup_version '1.5.50'
launcher_version '13458'
service_version '0.6.0' # WINDOWS ONLY
end
# Set latest version of packages to retain
hab_sup 'default' do
bldr_url 'https://bldr.private.net'
sup_version '1.5.86'
launcher_version '13458'
service_version '0.6.0' # WINDOWS ONLY
keep_latest '2'
end
hab_config
Applies a given configuration to a habitat service using hab config apply
.
Actions
apply
: (default action) apply the given configuration
Properties
service_group
: The service group to apply the configuration to, for example,nginx.default
config
: The configuration to apply as a ruby hash, for example,{ worker_count: 2, http: { keepalive_timeout: 120 } }
remote_sup
: Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632]remote_sup_http
: Address for remote supervisor http port. Used to pull existing configuration data. If this is invalid, config will be applied on every Chef run.gateway_auth_token
: Auth token for accessing the remote supervisor's http port.user
: Name of user key to use for encryption. Passes--user
tohab config apply
Notes
The version number of the configuration is automatically generated and will be the current timestamp in seconds since 1970-01-01 00:00:00 UTC.
Examples
hab_config 'nginx.default' do
config({
worker_count: 2,
http: {
keepalive_timeout: 120
}
})
end
hab_user_toml
Templates a user.toml for the specified service. This is written to /hab/user/<service_name>/config/user.toml
. User.toml can be used to set configuration overriding the default.toml for a given package as an alternative to applying service group level configuration.
Actions
create
: (default action) Create the user.toml from the specified config.delete
: Delete the user.toml
Properties
service_name
: The service group to apply the configuration to, for example,nginx.default
config
: Only valid for:create
action. The configuration to apply as a ruby hash, for example,{ worker_count: 2, http: { keepalive_timeout: 120 } }
Examples
hab_user_toml 'nginx' do
config({
worker_count: 2,
http: {
keepalive_timeout: 120
}
})
end
Maintainers
This cookbook is maintained by the following maintainers:
- Jon Cowie jcowie@chef.io
- Jeff Brimager jbrimager@chef.io
- Collin Mcneese cmcneese@chef.io
The goal of the Community Cookbook Engineering team is to improve cookbook quality and to aid the community in contributing to cookbooks. To learn more about our team, process, and design goals see our team documentation. To learn more about contributing to cookbooks like this see our contributing documentation, or if you have general questions about this cookbook come chat with us in #cookbok-engineering on the Chef Community Slack
License
Copyright: 2016-2018, Chef Software, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.