diff options
author | Tim Smith <tsmith@chef.io> | 2021-07-13 12:07:18 -0700 |
---|---|---|
committer | John McCrae <john.mccrae@progress.com> | 2021-07-16 15:38:16 -0700 |
commit | ccd5cf4a9fed266593f95fc95674139b1e55d0b4 (patch) | |
tree | 6ac319cd6d37943a97169b35bca1fd55f43668dd | |
parent | 7782ef0bba0fee794d61f4485bb1c3373b6b977e (diff) | |
download | chef-ccd5cf4a9fed266593f95fc95674139b1e55d0b4.tar.gz |
Update descriptions for the new habitat resources
Use our standard description format
Indent the properties to make them easier to read
Remove defaults from the property descriptions since that's generated
Skip documenting the state properties
Signed-off-by: Tim Smith <tsmith@chef.io>
-rw-r--r-- | lib/chef/resource/habitat/habitat_package.rb | 23 | ||||
-rw-r--r-- | lib/chef/resource/habitat/habitat_sup.rb | 134 | ||||
-rw-r--r-- | lib/chef/resource/habitat_config.rb | 41 | ||||
-rw-r--r-- | lib/chef/resource/habitat_install.rb | 53 | ||||
-rw-r--r-- | lib/chef/resource/habitat_service.rb | 119 | ||||
-rw-r--r-- | lib/chef/resource/habitat_user_toml.rb | 18 |
6 files changed, 209 insertions, 179 deletions
diff --git a/lib/chef/resource/habitat/habitat_package.rb b/lib/chef/resource/habitat/habitat_package.rb index c4827aba40..74221f5d71 100644 --- a/lib/chef/resource/habitat/habitat_package.rb +++ b/lib/chef/resource/habitat/habitat_package.rb @@ -25,59 +25,74 @@ class Chef provides :habitat_package use "habitat_shared" - description "Install the specified Habitat package from Habitat Builder." + description "Use the **habitat_package** to install or remove Chef Habitat packages from Habitat Builder." introduced "17.3" - examples <<~DOC - ```ruby - **Install core/redis** + ```ruby habitat_package 'core/redis' + ``` **Install specific version of a package from the unstable channel** + ```ruby habitat_package 'core/redis' do version '3.2.3' channel 'unstable' end + ``` **Install a package with specific version and revision** + ```ruby habitat_package 'core/redis' do version '3.2.3/20160920131015' end + ``` **Install a package and force linking it's binary files to the system path** + ```ruby habitat_package 'core/nginx' do binlink :force end + ``` **Install a package and link it's binary files to the system path** + + ```ruby habitat_package 'core/nginx' do options '--binlink' end + ``` **Remove package and all of it's versions** + ```ruby habitat_package 'core/nginx' action :remove end + ``` **Remove specified version of a package** + ```ruby habitat_package 'core/nginx/3.2.3' action :remove end + ``` **Remove package but retain some versions Note: Only available as of Habitat 1.5.86** + ```ruby habitat_package 'core/nginx' keep_latest '2' action :remove end + ``` + ```ruby **Remove package but keep dependencies** habitat_package 'core/nginx' no_deps false diff --git a/lib/chef/resource/habitat/habitat_sup.rb b/lib/chef/resource/habitat/habitat_sup.rb index 331d821a73..737883bc8e 100644 --- a/lib/chef/resource/habitat/habitat_sup.rb +++ b/lib/chef/resource/habitat/habitat_sup.rb @@ -26,8 +26,79 @@ class Chef false end - description "Runs a Habitat Supervisor for one or more Habitat Services. It is used in conjunction with `habitat_service` which will manage the services loaded and started within the supervisor." + description "Use the **habitat_sup** resource to runs a Chef Habitat supervisor for one or more Chef Habitat services. The resourceis commonly used in conjunction with `habitat_service` which will manage the services loaded and started within the supervisor." introduced "17.3" + examples <<~DOC + **Set up with just the defaults** + + ```ruby + habitat_sup 'default' + ``` + + **Update listen ports and use Supervisor toml config** + + ```ruby + habitat_sup 'test-options' do + listen_http '0.0.0.0:9999' + listen_gossip '0.0.0.0:9998' + toml_config true + end + ``` + + **Use with an on-prem Habitat Builder. Note: Access to public builder may not be available due to your company policies** + + ```ruby + habitat_sup 'default' do + bldr_url 'https://bldr.private.net' + end + ``` + + **Using update_condition** + + ```ruby + habitat_sup 'default' do + bldr_url 'https://bldr.private.net' + habitat_channel 'dev' + update_condition 'track-channel' + end + ``` + + **Provide event_stream_* information** + + ```ruby + habitat_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** + + ```ruby + habitat_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** + + habitat_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 + ``` + DOC property :bldr_url, String, description: "The Habitat Builder URL for the `habitat_package` resource, if needed." @@ -112,67 +183,6 @@ class Chef property :toml_config, [true, false], default: false, description: "Supports using the Supervisor toml configuration instead of passing exec parameters to the service, [reference](https://www.habitat.sh/docs/reference/#supervisor-config)." - examples <<~DOC - ```ruby - **Set up with just the defaults** - - habitat_sup 'default' - - **Update listen ports and use Supervisor toml config** - - habitat_sup 'test-options' do - listen_http '0.0.0.0:9999' - listen_gossip '0.0.0.0:9998' - toml_config true - end - - **Use with an on-prem Habitat Builder. Note: Access to public builder may not be available due to your company policies** - - habitat_sup 'default' do - bldr_url 'https://bldr.private.net' - end - - **Using update_condition** - - habitat_sup 'default' do - bldr_url 'https://bldr.private.net' - habitat_channel 'dev' - update_condition 'track-channel' - end - - **Provide event_stream_* information** - - habitat_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** - - habitat_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** - - habitat_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 - ``` - DOC - action :run, description: "The `run` action handles installing Habitat using the `habitat_install` resource, ensures that the appropriate versions of the `core/hab-sup` and `core/hab-launcher` packages are installed using `habitat_package`, and then drops off the appropriate init system definitions and manages the service." do habitat_install new_resource.name do license new_resource.license diff --git a/lib/chef/resource/habitat_config.rb b/lib/chef/resource/habitat_config.rb index 5a7333b078..8047c47c2c 100644 --- a/lib/chef/resource/habitat_config.rb +++ b/lib/chef/resource/habitat_config.rb @@ -24,30 +24,12 @@ class Chef provides :habitat_config - property :config, Mash, required: true, coerce: proc { |m| m.is_a?(Hash) ? Mash.new(m) : m }, - description: "The configuration to apply as a ruby hash, for example, `{ worker_count: 2, http: { keepalive_timeout: 120 } }`." - - property :service_group, String, name_property: true, desired_state: false, - description: "The service group to apply the configuration to. For example, `nginx.default`" - - property :remote_sup, String, default: "127.0.0.1:9632", desired_state: false, - description: "Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632]." - # Http port needed for querying/comparing current config value - property :remote_sup_http, String, default: "127.0.0.1:9631", desired_state: false, - description: "Address for remote supervisor http port. Used to pull existing." - - property :gateway_auth_token, String, desired_state: false, - description: "Auth token for accessing the remote supervisor's http port." - - property :user, String, desired_state: false, - description: "Name of user key to use for encryption. Passes `--user` to `hab config apply`." - - description "Applies a given configuration to a habitat service using `hab config apply`." + description "Use the **habitat_config** resource to apply a configuration to a Chef Habitat service." introduced "17.3" examples <<~DOC - ```ruby **Configure your nginx defaults** + ```ruby habitat_config 'nginx.default' do config({ worker_count: 2, @@ -59,6 +41,25 @@ class Chef ``` DOC + property :config, Mash, required: true, coerce: proc { |m| m.is_a?(Hash) ? Mash.new(m) : m }, + description: "The configuration to apply as a ruby hash, for example, `{ worker_count: 2, http: { keepalive_timeout: 120 } }`." + + property :service_group, String, name_property: true, desired_state: false, + description: "The service group to apply the configuration to. For example, `nginx.default`" + + property :remote_sup, String, default: "127.0.0.1:9632", desired_state: false, + description: "Address to a remote Supervisor's Control Gateway." + + # Http port needed for querying/comparing current config value + property :remote_sup_http, String, default: "127.0.0.1:9631", desired_state: false, + description: "Address for remote supervisor http port. Used to pull existing." + + property :gateway_auth_token, String, desired_state: false, + description: "Auth token for accessing the remote supervisor's http port." + + property :user, String, desired_state: false, + description: "Name of user key to use for encryption. Passes `--user` to `hab config apply`." + load_current_value do http_uri = "http://#{remote_sup_http}" diff --git a/lib/chef/resource/habitat_install.rb b/lib/chef/resource/habitat_install.rb index 6980594636..86d979a35a 100644 --- a/lib/chef/resource/habitat_install.rb +++ b/lib/chef/resource/habitat_install.rb @@ -22,44 +22,26 @@ class Chef unified_mode true provides :habitat_install - description "This resource will install the newest stable version of habitat." + description "Use the **habitat_install** resource to install Chef Habitat." introduced "17.3" - - property :name, String, default: "install habitat", - description: "name for your resource block." - - property :install_url, String, default: "https://raw.githubusercontent.com/habitat-sh/habitat/master/components/hab/install.sh", - description: "URL to the install script, default is from the [habitat repo](https://raw.githubusercontent.com/habitat-sh/habitat/master/components/hab/install.sh) ." - - property :bldr_url, String, - description: "Optional URL to an alternate Habitat Builder." - - property :create_user, [true, false], default: true, - description: "Creates the `hab` system user." - - property :tmp_dir, String, - description: "Sets TMPDIR environment variable for location to place temp files. Note: This is required if `/tmp` and `/var/tmp` are mounted `noexec`." - - property :license, String, equal_to: ["accept"], - description: "Specifies acceptance of habitat license when set to `accept`." - - property :hab_version, String, - description: "Specify the version of `Habitat` you would like to install." - examples <<~DOC - ```ruby - **Nameless Installation** + **Installation Without a Resource Name** + ```ruby habitat_install + ``` **Installation specifying a habitat builder URL** + ```ruby habitat_install 'install habitat' do bldr_url 'http://localhost' end + ``` **Installation specifying version and habitat builder URL** + ```ruby habitat_install 'install habitat' do bldr_url 'http://localhost' hab_version '1.5.50' @@ -67,6 +49,27 @@ class Chef ``` DOC + property :name, String, default: "install habitat", + description: "Name of the resource block. This has no impact other than logging." + + property :install_url, String, default: "https://raw.githubusercontent.com/habitat-sh/habitat/master/components/hab/install.sh", + description: "URL to the install script, default is from the [habitat repo](https://raw.githubusercontent.com/habitat-sh/habitat/master/components/hab/install.sh) ." + + property :bldr_url, String, + description: "Optional URL to an alternate Habitat Builder." + + property :create_user, [true, false], default: true, + description: "Creates the `hab` system user." + + property :tmp_dir, String, + description: "Sets TMPDIR environment variable for location to place temp files. Note: This is required if `/tmp` and `/var/tmp` are mounted `noexec`." + + property :license, String, equal_to: ["accept"], + description: "Specifies acceptance of habitat license when set to `accept`." + + property :hab_version, String, + description: "Specify the version of `Habitat` you would like to install." + action :install, description: "Installs Habitat. Does nothing if the `hab` 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)" do if ::File.exist?(hab_path) cmd = shell_out!([hab_path, "--version"].flatten.compact.join(" ")) diff --git a/lib/chef/resource/habitat_service.rb b/lib/chef/resource/habitat_service.rb index 21e4fec4eb..41678ce032 100644 --- a/lib/chef/resource/habitat_service.rb +++ b/lib/chef/resource/habitat_service.rb @@ -22,68 +22,12 @@ class Chef unified_mode true provides :habitat_service - property :service_name, String, name_property: true, - description: "name property, the name of the service, must be in the form of `origin/name`" - - property :loaded, [true, false], default: false, - description: "state property indicating whether the service is loaded in the supervisor" - - property :running, [true, false], default: false, - description: "state property indicating whether the service is running in the supervisor" - # hab svc options which get included based on the action of the resource - property :strategy, [Symbol, String], equal_to: [:none, "none", :'at-once', "at-once", :rolling, "rolling"], default: :none, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, - description: "Passes `--strategy` with the specified update strategy to the hab command. Defaults to `:none`. Other options are `:'at-once'` and `:rolling`" - - property :topology, [Symbol, String], equal_to: [:standalone, "standalone", :leader, "leader"], default: :standalone, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, - description: "Passes `--topology` with the specified service topology to the hab command" - - property :bldr_url, String, default: "https://bldr.habitat.sh/", - description: "Passes `--url` with the specified Habitat Builder URL to the hab command. Depending on the type of Habitat Builder you are connecting to, this URL will look different, here are the **3** current types: - - Public Habitat Builder (default) - `https://bldr.habitat.sh` - - On-Prem Habitat Builder installed using the [Source Install Method](https://github.com/habitat-sh/on-prem-builder) - `https://your.bldr.url` - - On-Prem Habitat Builder installed using the [Automate Installer](https://automate.chef.io/docs/on-prem-builder/) - `https://your.bldr.url/bldr/v1`" - - property :channel, [Symbol, String], default: :stable, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, - description: "Passes `--channel` with the specified channel to the hab command" - - property :bind, [String, Array], coerce: proc { |b| b.is_a?(String) ? [b] : b }, default: [], - description: "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." - - property :binding_mode, [Symbol, String], equal_to: [:strict, "strict", :relaxed, "relaxed"], default: :strict, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, - description: "Passes `--binding-mode` with the specified binding mode. Defaults to `:strict`. Options are `:strict` or `:relaxed`" - - property :service_group, String, default: "default", - description: " Passes `--group` with the specified service group to the hab command" - - property :shutdown_timeout, Integer, default: 8 - - property :health_check_interval, Integer, default: 30, - description: "The interval (seconds) on which to run health checks (defaults to 30)" - - property :remote_sup, String, default: "127.0.0.1:9632", desired_state: false, - description: "Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632]" - # Http port needed for querying/comparing current config value - property :remote_sup_http, String, default: "127.0.0.1:9631", desired_state: false, - description: "Address for remote supervisor http port. Used to pull existing configuration data. If this is invalid, config will be applied on every Chef run." - - property :gateway_auth_token, String, desired_state: false, - description: "Auth token for accessing the remote supervisor's http port." - - property :update_condition, [Symbol, String], equal_to: [:latest, "latest", :'track-channel', "track-channel"], default: :latest, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, - description: "Passes `--update-condition` dictating when this service should updated. Defaults to `latest`. Options are `latest` or `track-channel` **_Note: This requires a minimum habitat version of 1.5.71_** - - `latest`: 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." - - description "Manages a Habitat application service using `hab sup`/`hab service`. This requires that `core/hab-sup` be running as a service. See the `habitat_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. - " + description "Use the **habitat_service** resource to manage Chef Habitat services. This requires that `core/hab-sup` be running as a service. See the `habitat_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." introduced "17.3" examples <<~DOC - - ```ruby **Install and load nginx** + ```ruby habitat_package 'core/nginx' habitat_service 'core/nginx' @@ -91,16 +35,20 @@ class Chef service_name 'core/nginx' action :unload end + ``` **Pass the `strategy` and `topology` options to hab service commands** + ```ruby habitat_service 'core/redis' do strategy 'rolling' topology 'standalone' end + ``` **Using update_condition** + ```ruby habitat_service 'core/redis' do strategy 'rolling' update_condition 'track-channel' @@ -123,6 +71,61 @@ class Chef ``` DOC + property :service_name, String, name_property: true, + description: "The name of the service, must be in the form of `origin/name`" + + property :loaded, [true, false], default: false, skip_docs: true, + description: "state property indicating whether the service is loaded in the supervisor" + + property :running, [true, false], default: false, skip_docs: true, + description: "state property indicating whether the service is running in the supervisor" + + # hab svc options which get included based on the action of the resource + property :strategy, [Symbol, String], equal_to: [:none, "none", :'at-once', "at-once", :rolling, "rolling"], default: :none, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, + description: "Passes `--strategy` with the specified update strategy to the hab command. Defaults to `:none`. Other options are `:'at-once'` and `:rolling`" + + property :topology, [Symbol, String], equal_to: [:standalone, "standalone", :leader, "leader"], default: :standalone, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, + description: "Passes `--topology` with the specified service topology to the hab command" + + property :bldr_url, String, default: "https://bldr.habitat.sh/", + description: "Passes `--url` with the specified Habitat Builder URL to the hab command. Depending on the type of Habitat Builder you are connecting to, this URL will look different, here are the **3** current types: + - Public Habitat Builder (default) - `https://bldr.habitat.sh` + - On-Prem Habitat Builder installed using the [Source Install Method](https://github.com/habitat-sh/on-prem-builder) - `https://your.bldr.url` + - On-Prem Habitat Builder installed using the [Automate Installer](https://automate.chef.io/docs/on-prem-builder/) - `https://your.bldr.url/bldr/v1`" + + property :channel, [Symbol, String], default: :stable, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, + description: "Passes `--channel` with the specified channel to the hab command" + + property :bind, [String, Array], coerce: proc { |b| b.is_a?(String) ? [b] : b }, default: [], + description: "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." + + property :binding_mode, [Symbol, String], equal_to: [:strict, "strict", :relaxed, "relaxed"], default: :strict, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, + description: "Passes `--binding-mode` with the specified binding mode. Defaults to `:strict`. Options are `:strict` or `:relaxed`" + + property :service_group, String, default: "default", + description: " Passes `--group` with the specified service group to the hab command" + + property :shutdown_timeout, Integer, default: 8, + description: "The timeout in seconds allowed during shutdown." + + property :health_check_interval, Integer, default: 30, + description: "The interval (seconds) on which to run health checks." + + property :remote_sup, String, default: "127.0.0.1:9632", desired_state: false, + description: "Address to a remote Supervisor's Control Gateway" + + # Http port needed for querying/comparing current config value + property :remote_sup_http, String, default: "127.0.0.1:9631", desired_state: false, + description: "Address for remote supervisor http port. Used to pull existing configuration data. If this is invalid, config will be applied on every Chef run." + + property :gateway_auth_token, String, desired_state: false, + description: "Auth token for accessing the remote supervisor's http port." + + property :update_condition, [Symbol, String], equal_to: [:latest, "latest", :'track-channel', "track-channel"], default: :latest, coerce: proc { |s| s.is_a?(String) ? s.to_sym : s }, + description: "Passes `--update-condition` dictating when this service should updated. Defaults to `latest`. Options are `latest` or `track-channel` **_Note: This requires a minimum habitat version of 1.5.71_** + - `latest`: 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." + load_current_value do service_details = get_service_details(service_name) diff --git a/lib/chef/resource/habitat_user_toml.rb b/lib/chef/resource/habitat_user_toml.rb index a1bb70f4d0..83053b9327 100644 --- a/lib/chef/resource/habitat_user_toml.rb +++ b/lib/chef/resource/habitat_user_toml.rb @@ -19,20 +19,12 @@ class Chef unified_mode true provides :habitat_user_toml - property :config, Mash, - required: true, - coerce: proc { |m| m.is_a?(Hash) ? Mash.new(m) : m }, - description: "Only valid for `:create` action. The configuration to apply as a ruby hash, for example, `{ worker_count: 2, http: { keepalive_timeout: 120 } }`." - - property :service_name, String, name_property: true, desired_state: false, - description: "The service group to apply the configuration to, for example, `nginx.default`." - - description "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." + description "Use the **habitat_user_toml** to templates a `user.toml` for Chef Habitat services. 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." introduced "17.3" examples <<~DOC - ```ruby **Configure user specific settings to nginx** + ```ruby habitat_user_toml 'nginx' do config({ worker_count: 2, @@ -44,6 +36,12 @@ class Chef ``` DOC + property :config, Mash, required: true, coerce: proc { |m| m.is_a?(Hash) ? Mash.new(m) : m }, + description: "Only valid for `:create` action. The configuration to apply as a ruby hash, for example, `{ worker_count: 2, http: { keepalive_timeout: 120 } }`." + + property :service_name, String, name_property: true, desired_state: false, + description: "The service group to apply the configuration to, for example, `nginx.default`." + action :create, description: "(default action) Create the user.toml from the specified config." do directory config_directory do mode "0755" |