| Option |
Description |
Extended Description |
--basedir DIRNAME
|
Use an alternate base directory (git checkout of puppet repository)
|
Option to set the base checkout directory of puppet repository (basedir.rb)
|
--bootstrap-current
|
Run bootstrap script for the current directory too
|
Option to bootstrap the current directory (by default, the bootstrap script is NOT
run when the catalog builds in the current directory). (bootstrap_current.rb)
|
--bootstrap-environment "key1=val1,key2=val2,..."
|
Bootstrap script environment variables in key=value format
|
Allow the bootstrap environment to be set up via the command line. (bootstrap_environment.rb)
|
--bootstrap-script FILENAME
|
Bootstrap script relative to checkout directory
|
Allow specification of a bootstrap script. This runs after checking out the directory, and before running
puppet there. Good for running librarian to install modules, and anything else site-specific that needs
to be done. (bootstrap_script.rb)
|
--bootstrap-then-exit
|
Bootstrap from-dir and/or to-dir and then exit
|
Option to bootstrap directories and then exit (bootstrap_then_exit.rb)
|
--bootstrapped-from-dir DIRNAME
|
Use a pre-bootstrapped 'from' directory
|
Allow (or create) directories that are already bootstrapped. Handy to allow "bootstrap once, build many"
to save time when diffing multiple catalogs on this system. (bootstrapped_dirs.rb)
|
--bootstrapped-to-dir DIRNAME
|
Use a pre-bootstrapped 'to' directory
|
Allow (or create) directories that are already bootstrapped. Handy to allow "bootstrap once, build many"
to save time when diffing multiple catalogs on this system. (bootstrapped_dirs.rb)
|
--cached-master-dir PATH
|
Cache bootstrapped origin/master at this path
|
Cache a bootstrapped checkout of 'master' and use that for time-saving when the SHA
has not changed. (cached_master_dir.rb)
|
--catalog-only
--no-catalog-only
|
Only compile the catalog for the "to" branch but do not diff
|
When set, --catalog-only will only compile the catalog for the 'to' branch, and skip any
diffing activity. The catalog will be printed to STDOUT or written to the output file. (catalog_only.rb)
|
--color
--no-color
|
Enable/disable colors in output
|
Color printing option (color.rb)
|
--command-line STRING1[,STRING2[,...]]
|
Command line arguments globally
|
Provide additional command line flags to set when running Puppet to compile catalogs. (command_line.rb)
|
--compare-file-text
--no-compare-file-text
|
Compare text, not source location, of file resources
|
When a file is specified with `source => 'puppet:///modules/something/foo.txt'`, remove
the 'source' attribute and populate the 'content' attribute with the text of the file.
This allows for a diff of the content, rather than a diff of the location, which is
what is most often desired. (compare_file_text.rb)
|
--compare-file-text-ignore-tags STRING1[,STRING2[,...]]
|
Tags that exclude a file resource from text comparison
|
When a file is specified with `source => 'puppet:///modules/something/foo.txt'`, remove
the 'source' attribute and populate the 'content' attribute with the text of the file.
This allows for a diff of the content, rather than a diff of the location, which is
what is most often desired. (compare_file_text.rb)
|
--create-symlinks STRING1[,STRING2[,...]]
|
Symlinks to create globally
|
Specify which directories from the base should be symlinked into the temporary compilation
environment. This is useful only in conjunction with `--preserve-environments`. (create_symlinks.rb)
|
-d
--debug
--no-debug
|
Print debugging messages to STDERR
|
Debugging option (debug.rb)
|
--debug-bootstrap
|
Print debugging output for bootstrap script
|
Option to print debugging output for the bootstrap script in addition to the normal
debugging output. Note that `--debug` must also be enabled for this option to have
any effect. (debug_bootstrap.rb)
|
--default-header
|
Print default header with output
|
Provide ability to set custom header or to display no header at all (header.rb)
|
--display-datatype-changes
--no-display-datatype-changes
|
Display changes in data type even when strings match
|
Toggle on or off the display of data type changes when the string representation
is the same. For example with this enabled, '42' (the string) and 42 (the integer)
will be displayed as a difference. With this disabled, this is not displayed as a
difference. (display_datatype_changes.rb)
|
--display-detail-add
--no-display-detail-add
|
Display parameters and other details for added resources
|
Provide ability to display details of 'added' resources in the output. (display_detail_add.rb)
|
--display-source
--no-display-source
|
Show source file and line for each difference
|
Display source filename and line number for diffs (display_source_file_line.rb)
|
--enc PATH
|
Path to ENC script, relative to checkout directory or absolute
|
Path to external node classifier, relative to the base directory of the checkout. (enc.rb)
|
--enc-override STRING1[,STRING2[,...]]
|
Override parameter from ENC globally
|
Allow override of ENC parameters on the command line. ENC parameter overrides can be supplied for the 'to' or 'from' catalog,
or for both. There is some attempt to handle data types here (since all items on the command line are strings)
by permitting a data type specification as well. For parameters nested in hashes, use `::` as the delimiter. (enc_override.rb)
|
--environment STRING
|
Environment for catalog compilation globally
|
Specify the environment to use when compiling the catalog. This is useful only in conjunction
with `--preserve-environments`. (environment.rb)
|
--fact-file STRING
|
Override fact globally
|
Allow an existing fact file to be provided, to avoid pulling facts from PuppetDB. (fact_file.rb)
|
--fact-override STRING1[,STRING2[,...]]
|
Override fact globally
|
Allow override of facts on the command line. Fact overrides can be supplied for the 'to' or 'from' catalog,
or for both. There is some attempt to handle data types here (since all items on the command line are strings)
by permitting a data type specification as well. (fact_override.rb)
|
--facts-terminus STRING
|
Facts terminus: one of yaml, facter
|
Get the facts terminus. Generally this is 'yaml' and a fact file will be loaded from PuppetDB or
elsewhere in the environment. However it can be set to 'facter' which will run facter on the host
on which this is running. (facts_terminus.rb)
|
--filters FILTER1[,FILTER2[,...]]
|
Filters to apply
|
Specify one or more filters to apply to the results of the catalog difference.
For a list of available filters and further explanation, please refer to
Filtering results. (filters.rb)
|
-f FROM_BRANCH
--from FROM_BRANCH
|
Branch you are coming from
|
Set the 'from' and 'to' branches, which is used to compile catalogs. A branch of '.' means to use
the current contents of the base code directory without any git checkouts. (to_from_branch.rb)
|
--from-catalog FILENAME
|
Use a pre-compiled catalog 'from'
|
If pre-compiled catalogs are available, these can be used to short-circuit the build process.
These files must exist and be in Puppet catalog format. (existing_catalogs.rb)
|
--from-command-line STRING1[,STRING2[,...]]
|
Command line arguments for the from branch
|
Provide additional command line flags to set when running Puppet to compile catalogs. (command_line.rb)
|
--from-create-symlinks STRING1[,STRING2[,...]]
|
Symlinks to create for the from branch
|
Specify which directories from the base should be symlinked into the temporary compilation
environment. This is useful only in conjunction with `--preserve-environments`. (create_symlinks.rb)
|
--from-enc PATH
|
Path to ENC script (for the from catalog only)
|
Path to external node classifier, relative to the base directory of the checkout. (enc.rb)
|
--from-enc-override STRING1[,STRING2[,...]]
|
Override parameter from ENC for the from branch
|
Allow override of ENC parameters on the command line. ENC parameter overrides can be supplied for the 'to' or 'from' catalog,
or for both. There is some attempt to handle data types here (since all items on the command line are strings)
by permitting a data type specification as well. For parameters nested in hashes, use `::` as the delimiter. (enc_override.rb)
|
--from-environment STRING
|
Environment for catalog compilation for the from branch
|
Specify the environment to use when compiling the catalog. This is useful only in conjunction
with `--preserve-environments`. (environment.rb)
|
--from-fact-file STRING
|
Override fact for the from branch
|
Allow an existing fact file to be provided, to avoid pulling facts from PuppetDB. (fact_file.rb)
|
--from-fact-override STRING1[,STRING2[,...]]
|
Override fact for the from branch
|
Allow override of facts on the command line. Fact overrides can be supplied for the 'to' or 'from' catalog,
or for both. There is some attempt to handle data types here (since all items on the command line are strings)
by permitting a data type specification as well. (fact_override.rb)
|
--from-hiera-config STRING
|
Full or relative path to global Hiera configuration file for the from branch
|
Specify a relative path to the Hiera yaml file (hiera_config.rb)
|
--from-hiera-path STRING
|
Path to hiera data directory, relative to top directory of repository for the from branch
|
Specify the path to the Hiera data directory (relative to the top level Puppet checkout). For Puppet Enterprise and the
Puppet control repo template, the value of this should be 'hieradata', which is the default. (hiera_path.rb)
|
--from-hiera-path-strip STRING
|
Path prefix to strip when munging hiera.yaml for the from branch
|
Specify the path to strip off the datadir to munge hiera.yaml file (hiera_path_strip.rb)
|
--from-puppet-binary STRING
|
Full path to puppet binary for the from branch
|
Set --puppet-binary, --to-puppet-binary, --from-puppet-binary (puppet_binary.rb)
|
--from-puppet-master STRING
|
Hostname or Hostname:PortNumber for Puppet Master for the from branch
|
Specify the hostname, or hostname:port, for the Puppet Master. (puppet_master.rb)
|
--from-puppet-master-api-version STRING
|
Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) for the from branch
|
Specify the API version to use for the Puppet Master. This makes it possible to authenticate to a
version 3.x PuppetMaster by specifying the API version as 2, or for a version 4.x PuppetMaster by
specifying API version as 3. (puppet_master_api_version.rb)
|
--from-puppet-master-ssl-ca STRING
|
Full path to CA certificate that signed the Puppet Master certificate for the from branch
|
Specify the CA certificate for Puppet Master. If specified, this will enable SSL verification
that the certificate being presented has been signed by this CA, and that the common name
matches the name you are using to connecting. (puppet_master_ssl_ca.rb)
|
--from-puppet-master-ssl-client-cert STRING
|
Full path to certificate file for SSL client auth to Puppet Master for the from branch
|
Specify the SSL client certificate for Puppet Master. This makes it possible to authenticate with a
client certificate keypair to the Puppet Master. (puppet_master_ssl_client_cert.rb)
|
--from-puppet-master-ssl-client-key STRING
|
Full path to key file for SSL client auth to Puppet Master for the from branch
|
Specify the SSL client key for Puppet Master. This makes it possible to authenticate with a
client certificate keypair to the Puppet Master. (puppet_master_ssl_client_key.rb)
|
--from-puppet-master-timeout STRING
|
Puppet Master catalog retrieval timeout in seconds for the from branch
|
Specify a timeout for retrieving a catalog from a Puppet master / Puppet server.
This timeout is specified in seconds. (puppet_master_timeout.rb)
|
--from-puppet-master-token STRING
|
PE RBAC token to authenticate to the Puppetserver API v4 for the from branch
|
Specify a PE RBAC token used to authenticate to Puppetserver for v4
catalog API calls. (puppet_master_token.rb)
|
--from-puppet-master-token-file STRING
|
File containing PE RBAC token to authenticate to the Puppetserver API v4 for the from branch
|
Specify a path to a file containing a PE RBAC token used to authenticate to the
Puppetserver for a v4 catalog API call. (puppet_master_token_file.rb)
|
--from-puppetdb
--no-from-puppetdb
|
Pull "from" catalog from PuppetDB instead of compiling
|
Set --from-puppetdb to pull most recent catalog from PuppetDB instead of compiling (from_puppetdb.rb)
|
--from-save-catalog STRING
|
Save intermediate catalogs into files for the from branch
|
Allow catalogs to be saved to a file before they are diff'd. (save_catalog.rb)
|
--header STRING
|
Specify header for output
|
Provide ability to set custom header or to display no header at all (header.rb)
|
--hiera-config STRING
|
Full or relative path to global Hiera configuration file globally
|
Specify a relative path to the Hiera yaml file (hiera_config.rb)
|
--hiera-path STRING
|
Path to hiera data directory, relative to top directory of repository globally
|
Specify the path to the Hiera data directory (relative to the top level Puppet checkout). For Puppet Enterprise and the
Puppet control repo template, the value of this should be 'hieradata', which is the default. (hiera_path.rb)
|
--hiera-path-strip STRING
|
Path prefix to strip when munging hiera.yaml globally
|
Specify the path to strip off the datadir to munge hiera.yaml file (hiera_path_strip.rb)
|
-n HOSTNAME1[,HOSTNAME2[,...]]
--hostname HOSTNAME1[,HOSTNAME2[,...]]
|
Use PuppetDB facts from last run of a hostname or a comma separated list of multiple hostnames
|
Set hostname, which is used to look up facts in PuppetDB, and in the header of diff display.
This option can recieve a single hostname, or a comma separated list of
multiple hostnames, which are split into an Array. Multiple hostnames do not
work with the `catalog-only` or `bootstrap-then-exit` options. (hostname.rb)
|
--ignore "Type1[Title1],Type2[Title2],..."
|
More resources to ignore in format type[title]
|
Options used when comparing catalogs - set ignored changes. (ignore.rb)
|
--ignore-attr "attr1,attr2,..."
|
Attributes to ignore
|
Specify attributes to ignore (ignore_attr.rb)
|
--ignore-tags STRING1[,STRING2[,...]]
|
Specify tags to ignore
|
Provide ability to set one or more tags, which will cause catalog-diff
to ignore any changes for any defined type where this tag is set. (ignore_tags.rb)
|
--include-tags
--no-include-tags
|
Include changes to tags in the diff output
|
Options used when comparing catalogs - tags are generally ignored; you can un-ignore them. (include_tags.rb)
|
--master-cache-branch BRANCH
|
Branch to cache
|
Allow override of the branch that is cached. This defaults to 'origin/master'. (master_cache_branch.rb)
|
--no-enc
|
Disable ENC
|
Path to external node classifier, relative to the base directory of the checkout. (enc.rb)
|
--no-header
|
Do not print a header
|
Provide ability to set custom header or to display no header at all (header.rb)
|
--no-hiera-config
|
Disable hiera config file installation
|
Specify a relative path to the Hiera yaml file (hiera_config.rb)
|
--no-hiera-path
|
Do not use any default hiera path settings
|
Specify the path to the Hiera data directory (relative to the top level Puppet checkout). For Puppet Enterprise and the
Puppet control repo template, the value of this should be 'hieradata', which is the default. (hiera_path.rb)
|
--no-hiera-path-strip
|
Do not use any default hiera path strip settings
|
Specify the path to strip off the datadir to munge hiera.yaml file (hiera_path_strip.rb)
|
--no-ignore-tags
|
Disable ignoring based on tags
|
Provide ability to set one or more tags, which will cause catalog-diff
to ignore any changes for any defined type where this tag is set. (ignore_tags.rb)
|
-o FILENAME
--output-file FILENAME
|
Output results into FILENAME
|
Output file option (output_file.rb)
|
--output-format FORMAT
|
Output format: text,json,legacy_json
|
Output format option. 'text' is human readable text, 'json' is an array of differences
identified by human readable keys (the preferred octocatalog-diff 1.x format), and 'legacy_json' is an
array of differences, where each difference is an array (the octocatalog-diff 0.x format). (output_format.rb)
|
--override-script-path DIRNAME
|
Directory with scripts to override built-ins
|
Provide an optional directory to override default built-in scripts such as git checkout
and puppet version determination. (override_script_path.rb)
|
--parallel
--no-parallel
|
Enable or disable parallel processing
|
Disable or enable parallel processing of catalogs. (parallel.rb)
|
--parser PARSER_NAME
|
Specify parser (default, future)
|
Enable future parser for both branches or for just one (parser.rb)
|
--parser-from PARSER_NAME
|
Specify parser (default, future)
|
Enable future parser for both branches or for just one (parser.rb)
|
--parser-to PARSER_NAME
|
Specify parser (default, future)
|
Enable future parser for both branches or for just one (parser.rb)
|
--pass-env-vars VAR1[,VAR2[,...]]
|
Environment variables to pass
|
One or more environment variables that should be made available to the Puppet binary when parsing
the catalog. For example, --pass-env-vars FOO,BAR will make the FOO and BAR environment variables
available. Setting these variables is your responsibility outside of octocatalog-diff. (pass_env_vars.rb)
|
--pe-enc-ssl-ca FILENAME
|
CA certificate that signed the ENC API certificate
|
Specify the CA certificate for the Puppet Enterprise ENC. If specified, this will enable SSL verification
that the certificate being presented has been signed by this CA, and that the common name
matches the name you are using to connecting. (pe_enc_ssl_ca.rb)
|
--pe-enc-ssl-client-cert FILENAME
|
SSL client certificate to connect to PE ENC
|
Specify the client certificate for connecting to the Puppet Enterprise ENC. This must be specified along with
--pe-enc-ssl-client-key in order to work. (pe_enc_ssl_client_cert.rb)
|
--pe-enc-ssl-client-key FILENAME
|
SSL client key to connect to PE ENC
|
Specify the client key for connecting to Puppet Enterprise ENC. This must be specified along with
--pe-enc-ssl-client-cert in order to work. (pe_enc_ssl_client_key.rb)
|
--pe-enc-token TOKEN
|
Token to access the Puppet Enterprise ENC API
|
Specify the access token to access the Puppet Enterprise ENC. Refer to
https://docs.puppet.com/pe/latest/nc_forming_requests.html#authentication for
details on generating and obtaining a token. Use this option to specify the text
of the token. (Use --pe-enc-token-file to read the content of the token from a file.) (pe_enc_token.rb)
|
--pe-enc-token-file PATH
|
Path containing token for PE node classifier, relative or absolute
|
Specify the access token to access the Puppet Enterprise ENC. Refer to
https://docs.puppet.com/pe/latest/nc_forming_requests.html#authentication for
details on generating and obtaining a token. Use this option if the token is stored
in a file, to read the content of the token from the file. (pe_enc_token_file.rb)
|
--pe-enc-url URL
|
Base URL for Puppet Enterprise ENC endpoint
|
Specify the URL to the Puppet Enterprise ENC API. By default, the node classifier service
listens on port 4433 and all endpoints are relative to the /classifier-api/ path. That means
the likely value for this option will be something like:
https://your-pe-console-server:4433/classifier-api (pe_enc_url.rb)
|
--preserve-environments
--no-preserve-environments
|
Enable or disable environment preservation
|
Preserve the `environments` directory from the repository when compiling the catalog. Likely
requires some combination of `--to-environment`, `--from-environment`, and/or `--create-symlinks`
to work correctly. (preserve_environments.rb)
|
--puppet-binary STRING
|
Full path to puppet binary globally
|
Set --puppet-binary, --to-puppet-binary, --from-puppet-binary (puppet_binary.rb)
|
--puppet-master STRING
|
Hostname or Hostname:PortNumber for Puppet Master globally
|
Specify the hostname, or hostname:port, for the Puppet Master. (puppet_master.rb)
|
--puppet-master-api-version STRING
|
Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) globally
|
Specify the API version to use for the Puppet Master. This makes it possible to authenticate to a
version 3.x PuppetMaster by specifying the API version as 2, or for a version 4.x PuppetMaster by
specifying API version as 3. (puppet_master_api_version.rb)
|
--puppet-master-ssl-ca STRING
|
Full path to CA certificate that signed the Puppet Master certificate globally
|
Specify the CA certificate for Puppet Master. If specified, this will enable SSL verification
that the certificate being presented has been signed by this CA, and that the common name
matches the name you are using to connecting. (puppet_master_ssl_ca.rb)
|
--puppet-master-ssl-client-cert STRING
|
Full path to certificate file for SSL client auth to Puppet Master globally
|
Specify the SSL client certificate for Puppet Master. This makes it possible to authenticate with a
client certificate keypair to the Puppet Master. (puppet_master_ssl_client_cert.rb)
|
--puppet-master-ssl-client-key STRING
|
Full path to key file for SSL client auth to Puppet Master globally
|
Specify the SSL client key for Puppet Master. This makes it possible to authenticate with a
client certificate keypair to the Puppet Master. (puppet_master_ssl_client_key.rb)
|
--puppet-master-timeout STRING
|
Puppet Master catalog retrieval timeout in seconds globally
|
Specify a timeout for retrieving a catalog from a Puppet master / Puppet server.
This timeout is specified in seconds. (puppet_master_timeout.rb)
|
--puppet-master-token STRING
|
PE RBAC token to authenticate to the Puppetserver API v4 globally
|
Specify a PE RBAC token used to authenticate to Puppetserver for v4
catalog API calls. (puppet_master_token.rb)
|
--puppet-master-token-file STRING
|
File containing PE RBAC token to authenticate to the Puppetserver API v4 globally
|
Specify a path to a file containing a PE RBAC token used to authenticate to the
Puppetserver for a v4 catalog API call. (puppet_master_token_file.rb)
|
--puppetdb-api-version N
|
Version of PuppetDB API (3 or 4)
|
Specify the API version to use for the PuppetDB. The current values supported are '3' or '4', and '4' is
the default. (puppetdb_api_version.rb)
|
--puppetdb-package-inventory
--no-puppetdb-package-inventory
|
Include Puppet Enterprise package inventory data, if found
|
When pulling facts from PuppetDB in a Puppet Enterprise environment, also include
the Puppet Enterprise Package Inventory data in the fact results, if available.
Generally you should not need to specify this, but including the package inventory
data will produce a more accurate set of input facts for environments using
package inventory. (puppetdb_package_inventory.rb)
|
--puppetdb-ssl-ca FILENAME
|
CA certificate that signed the PuppetDB certificate
|
Specify the CA certificate for PuppetDB. If specified, this will enable SSL verification
that the certificate being presented has been signed by this CA, and that the common name
matches the name you are using to connecting. (puppetdb_ssl_ca.rb)
|
--puppetdb-ssl-client-cert FILENAME
|
SSL client certificate to connect to PuppetDB
|
Specify the client certificate for connecting to PuppetDB. This must be specified along with
--puppetdb-ssl-client-key in order to work. (puppetdb_ssl_client_cert.rb)
|
--puppetdb-ssl-client-key FILENAME
|
SSL client key to connect to PuppetDB
|
Specify the client key for connecting to PuppetDB. This must be specified along with
--puppetdb-ssl-client-cert in order to work. (puppetdb_ssl_client_key.rb)
|
--puppetdb-ssl-client-password PASSWORD
|
Password for SSL client key to connect to PuppetDB
|
Specify the password for a PEM or PKCS12 private key on the command line.
Note that `--puppetdb-ssl-client-password-file` is slightly more secure because
the text of the password won't appear in the process list. (puppetdb_ssl_client_password.rb)
|
--puppetdb-ssl-client-password-file FILENAME
|
Read password for SSL client key from a file
|
Specify the password for a PEM or PKCS12 private key, by reading it from a file. (puppetdb_ssl_client_password_file.rb)
|
--puppetdb-token TOKEN
|
Token to access the PuppetDB API
|
Specify the PE RBAC token to access the PuppetDB API. Refer to
https://puppet.com/docs/pe/latest/rbac/rbac_token_auth_intro.html#generate-a-token-using-puppet-access
for details on generating and obtaining a token. Use this option to specify the text
of the token. (Use --puppetdb-token-file to read the content of the token from a file.) (puppetdb_token.rb)
|
--puppetdb-token-file PATH
|
Path containing token for PuppetDB API, relative or absolute
|
Specify the PE RBAC token to access the PuppetDB API. Refer to
https://puppet.com/docs/pe/latest/rbac/rbac_token_auth_intro.html#generate-a-token-using-puppet-access
for details on generating and obtaining a token. Use this option to specify the text
in a file, to read the content of the token from the file. (puppetdb_token_file.rb)
|
--puppetdb-url URL
|
PuppetDB base URL
|
Specify the base URL for PuppetDB. This will generally look like https://puppetdb.yourdomain.com:8081 (puppetdb_url.rb)
|
-q
--quiet
--no-quiet
|
Quiet (no status messages except errors)
|
Quiet option (quiet.rb)
|
--retry-failed-catalog N
|
Retry building a failed catalog N times
|
Transient errors can cause catalog compilation problems. This adds an option to retry
a failed catalog multiple times before kicking out an error message. (retry_failed_catalog.rb)
|
--safe-to-delete-cached-master-dir PATH
|
OK to delete cached master directory at this path
|
By specifying a directory path here, you are explicitly giving permission to the program
to delete it if it believes it needs to be created (e.g., if the SHA has changed of the
cached directory). (safe_to_delete_cached_master_dir.rb)
|
--save-catalog STRING
|
Save intermediate catalogs into files globally
|
Allow catalogs to be saved to a file before they are diff'd. (save_catalog.rb)
|
--storeconfigs
--no-storeconfigs
|
Enable integration with puppetdb for collected resources
|
Set storeconfigs (integration with PuppetDB for collected resources) (storeconfigs.rb)
|
--suppress-absent-file-details
--no-suppress-absent-file-details
|
Suppress certain attributes of absent files
|
If enabled, this option will suppress changes to certain attributes of a file, if the
file is specified to be 'absent' in the target catalog. Suppressed changes in this case
include user, group, mode, and content, because a removed file has none of those.
This option is DEPRECATED; please use --filters AbsentFile instead. (suppress_absent_file_details.rb)
|
-t TO_BRANCH
--to TO_BRANCH
|
Branch you are going to
|
Set the 'from' and 'to' branches, which is used to compile catalogs. A branch of '.' means to use
the current contents of the base code directory without any git checkouts. (to_from_branch.rb)
|
--to-catalog FILENAME
|
Use a pre-compiled catalog 'to'
|
If pre-compiled catalogs are available, these can be used to short-circuit the build process.
These files must exist and be in Puppet catalog format. (existing_catalogs.rb)
|
--to-command-line STRING1[,STRING2[,...]]
|
Command line arguments for the to branch
|
Provide additional command line flags to set when running Puppet to compile catalogs. (command_line.rb)
|
--to-create-symlinks STRING1[,STRING2[,...]]
|
Symlinks to create for the to branch
|
Specify which directories from the base should be symlinked into the temporary compilation
environment. This is useful only in conjunction with `--preserve-environments`. (create_symlinks.rb)
|
--to-enc PATH
|
Path to ENC script (for the to catalog only)
|
Path to external node classifier, relative to the base directory of the checkout. (enc.rb)
|
--to-enc-override STRING1[,STRING2[,...]]
|
Override parameter from ENC for the to branch
|
Allow override of ENC parameters on the command line. ENC parameter overrides can be supplied for the 'to' or 'from' catalog,
or for both. There is some attempt to handle data types here (since all items on the command line are strings)
by permitting a data type specification as well. For parameters nested in hashes, use `::` as the delimiter. (enc_override.rb)
|
--to-environment STRING
|
Environment for catalog compilation for the to branch
|
Specify the environment to use when compiling the catalog. This is useful only in conjunction
with `--preserve-environments`. (environment.rb)
|
--to-fact-file STRING
|
Override fact for the to branch
|
Allow an existing fact file to be provided, to avoid pulling facts from PuppetDB. (fact_file.rb)
|
--to-fact-override STRING1[,STRING2[,...]]
|
Override fact for the to branch
|
Allow override of facts on the command line. Fact overrides can be supplied for the 'to' or 'from' catalog,
or for both. There is some attempt to handle data types here (since all items on the command line are strings)
by permitting a data type specification as well. (fact_override.rb)
|
--to-hiera-config STRING
|
Full or relative path to global Hiera configuration file for the to branch
|
Specify a relative path to the Hiera yaml file (hiera_config.rb)
|
--to-hiera-path STRING
|
Path to hiera data directory, relative to top directory of repository for the to branch
|
Specify the path to the Hiera data directory (relative to the top level Puppet checkout). For Puppet Enterprise and the
Puppet control repo template, the value of this should be 'hieradata', which is the default. (hiera_path.rb)
|
--to-hiera-path-strip STRING
|
Path prefix to strip when munging hiera.yaml for the to branch
|
Specify the path to strip off the datadir to munge hiera.yaml file (hiera_path_strip.rb)
|
--to-puppet-binary STRING
|
Full path to puppet binary for the to branch
|
Set --puppet-binary, --to-puppet-binary, --from-puppet-binary (puppet_binary.rb)
|
--to-puppet-master STRING
|
Hostname or Hostname:PortNumber for Puppet Master for the to branch
|
Specify the hostname, or hostname:port, for the Puppet Master. (puppet_master.rb)
|
--to-puppet-master-api-version STRING
|
Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) for the to branch
|
Specify the API version to use for the Puppet Master. This makes it possible to authenticate to a
version 3.x PuppetMaster by specifying the API version as 2, or for a version 4.x PuppetMaster by
specifying API version as 3. (puppet_master_api_version.rb)
|
--to-puppet-master-ssl-ca STRING
|
Full path to CA certificate that signed the Puppet Master certificate for the to branch
|
Specify the CA certificate for Puppet Master. If specified, this will enable SSL verification
that the certificate being presented has been signed by this CA, and that the common name
matches the name you are using to connecting. (puppet_master_ssl_ca.rb)
|
--to-puppet-master-ssl-client-cert STRING
|
Full path to certificate file for SSL client auth to Puppet Master for the to branch
|
Specify the SSL client certificate for Puppet Master. This makes it possible to authenticate with a
client certificate keypair to the Puppet Master. (puppet_master_ssl_client_cert.rb)
|
--to-puppet-master-ssl-client-key STRING
|
Full path to key file for SSL client auth to Puppet Master for the to branch
|
Specify the SSL client key for Puppet Master. This makes it possible to authenticate with a
client certificate keypair to the Puppet Master. (puppet_master_ssl_client_key.rb)
|
--to-puppet-master-timeout STRING
|
Puppet Master catalog retrieval timeout in seconds for the to branch
|
Specify a timeout for retrieving a catalog from a Puppet master / Puppet server.
This timeout is specified in seconds. (puppet_master_timeout.rb)
|
--to-puppet-master-token STRING
|
PE RBAC token to authenticate to the Puppetserver API v4 for the to branch
|
Specify a PE RBAC token used to authenticate to Puppetserver for v4
catalog API calls. (puppet_master_token.rb)
|
--to-puppet-master-token-file STRING
|
File containing PE RBAC token to authenticate to the Puppetserver API v4 for the to branch
|
Specify a path to a file containing a PE RBAC token used to authenticate to the
Puppetserver for a v4 catalog API call. (puppet_master_token_file.rb)
|
--to-save-catalog STRING
|
Save intermediate catalogs into files for the to branch
|
Allow catalogs to be saved to a file before they are diff'd. (save_catalog.rb)
|
--truncate-details
--no-truncate-details
|
Truncate details with --display-detail-add
|
When using `--display-detail-add` by default the details of any field will be truncated
at 80 characters. Specify `--no-truncate-details` to display the full output. This option
has no effect when `--display-detail-add` is not used. (truncate_details.rb)
|
--use-lcs
--no-use-lcs
|
Use the LCS algorithm to determine differences in arrays
|
Configures using the Longest common subsequence (LCS) algorithm to determine differences in arrays (use_lcs.rb)
|
--validate-references
--no-validate-references
|
References to validate
|
Confirm that each `before`, `require`, `subscribe`, and/or `notify` points to a valid
resource in the catalog. This value should be specified as an array of which of these
parameters are to be checked. (validate_references.rb)
|
## Using these options in API calls
Most of these options can also be used when making calls to the [API](/doc/dev/api.md).
Generally, parameters for the API are named corresponding to the names of the command line parameters, with dashes (`-`) converted to underscores (`_`). For example, the command line option `--hiera-config` is passed to the API as the symbol `:hiera_config`.
Each of the options above has a link to the source file where it is declared, should you wish to review the specific parameter names and data structures that are being set. octocatalog-diff-2.1.0/doc/requirements.md 0000664 0000000 0000000 00000004416 14341123201 0020525 0 ustar 00root root 0000000 0000000 # Requirements
To run `octocatalog-diff` you will need these basics:
- An appropriate Puppet version and [corresponding ruby version](https://puppet.com/docs/puppet/5.4/system_requirements.html)
- Puppet 5.x officially supports Ruby 2.4
- Puppet 4.x officially supports Ruby 2.1, but seems to work fine with later versions as well
- Puppet 3.8.7 -- we attempt to maintain compatibility in `octocatalog-diff` to facilitate upgrades even though this version is no longer supported by Puppet
- We don't officially support Puppet 3.8.6 or before
- Mac OS, Linux, or other Unix-line operating system (Windows is not supported)
- Ability to install gems, e.g. with [rbenv](https://github.com/rbenv/rbenv) or [rvm](https://rvm.io/), or root privileges to install into the system Ruby
- Puppet agent for [Linux](https://docs.puppet.com/puppet/latest/reference/install_linux.html) or [Mac OS X](https://docs.puppet.com/puppet/latest/reference/install_osx.html), or installed as a gem
We recommend that you also have the following to get the most out of `octocatalog-diff`, but these are not absolute requirements:
- If your Puppet code stored in a git repository, `octocatalog-diff` can check out branches for you as it does its comparisons. Your git repository can be stored on [GitHub.com](https://github.com/), [GitHub Enterprise](https://enterprise.github.com/home), or similar. If your Puppet code is not stored in a git repository, you can still point the tool at "from" and "to" directories, but you'll have to check them out yourself.
- If you have API access (HTTPS) to PuppetDB, `octocatalog-diff` can retrieve facts automatically and also support [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) if you use them. If you are not using PuppetDB or don't have access, the tool can still read facts from YAML files.
- If your site uses an [external node classifier](https://docs.puppet.com/guides/external_nodes.html), `octocatalog-diff` can execute the ENC script as part of its catalog compiles. Depending on how your ENC is designed, this may require network access or credentials to some service. If you are not using an ENC, that's fine. If you have an ENC but don't have the requisite access, depending on your setup the tool could produce unexpected results.
octocatalog-diff-2.1.0/doc/roadmap.md 0000664 0000000 0000000 00000002737 14341123201 0017431 0 ustar 00root root 0000000 0000000 # Roadmap
This document outlines our philosophy and goals for the continued development of `octocatalog-diff`.
## Goals
- Work on a system without a full Puppet installation
- Cause no added load on production Puppet masters (unless you specifically choose to do so with non-default options)
- Offer a command line tool to help make developers more efficient
- Offer the ability to in a Continuous Integration (CI) environment
- Be compatible with Puppet 3.8.7, 4.5, and later versions
- Provide flexibility to build and compare catalogs even in esoteric Puppet codebases
## Areas for future development
We are considering these areas for possible future development:
- Improved display of diffs, perhaps a web interface
- Additional CI use cases
- CI output display to summarize a change and a list of affected hosts, rather than listing all changes host-by-host
## Antipatterns
These are ideas we've evaluated and decided not to pursue. (If you are considering a [contribution](/.github/CONTRIBUTING.md) along these lines, please [open an issue](https://github.com/github/octocatalog-diff/issues/new) before start working on it. We would feel badly if you did a bunch of work that we could not accept.)
- Making this into a Puppet module with a "face" so that it can be run with `puppet octocatalog-diff ...` or similar. (We have specifically designed this tool to run without a full Puppet installation. There are [similar projects](/doc/similar.md) that are distributed as Puppet modules.)
octocatalog-diff-2.1.0/doc/similar.md 0000664 0000000 0000000 00000002367 14341123201 0017445 0 ustar 00root root 0000000 0000000 # Similar Projects
We are aware of the following projects that do similar things to octocatalog-diff:
- [Puppet's catalog_preview Puppet module](https://forge.puppet.com/puppetlabs/catalog_preview)
Installs as a module into your Puppet codebase and helps with migration from older Puppet versions to newer ones, or from open source Puppet to Puppet Enterprise. Also provides the ability to compare environments (branches). Requires a full working Puppet installation.
- [Zack Smith's catalog_diff Puppet module](https://forge.puppet.com/zack/catalog_diff)
Installs as a module into your Puppet codebase, allowing you to diff catalogs created by different versions of Puppet. Requires a full working Puppet installation.
- [camptocamp's puppet-catalog-diff-viewer](https://github.com/camptocamp/puppet-catalog-diff-viewer)
A viewer for JSON reports produced by the catalog_diff Puppet module.
`octocatalog-diff` differs from the above projects by running on a system without a fully configured Puppet installation (such as a developer workstation or CI server). This approach allows developers to run it without having access to the production Puppet servers, and it does not put any load on production Puppet masters when it compiles and compares catalogs.
octocatalog-diff-2.1.0/doc/troubleshooting.md 0000664 0000000 0000000 00000005052 14341123201 0021226 0 ustar 00root root 0000000 0000000 # Troubleshooting
Things not quite working as expected? This section will contain hints to help you get up and running.
### Make sure the tests pass
If you are getting errors from ruby, we'd really like to know if the tests are passing on your platform. Please follow the [installation instructions](/doc/installation.md#installing-from-source) to install octocatalog-diff from source, if you have not already done so. Once the repository is checked out, change into the directory run `rake` to perform the tests.
If you get test failures from a clean checkout of the master branch, please [open an issue](https://github.com/github/octocatalog-diff/issues/new) to let us know.
### Make sure your configuration file is found and error-free
Run the following command to test for the existence and integrity of your configuration file.
```
octocatalog-diff --config-test
```
If you get an error indicating that the file can't be found, or you get errors arising from the content of the file, please review the [configuration instructions](/doc/configuration.md) to make sure you've set things up correctly.
### Run the command in debug mode
Supplying `-d` on the command line, in addition to the node name and any other arguments, will provide a substantial amount of debugging information to the terminal window. If you ultimately end up requesting our help, we will need this debugging output.
Example:
```
octocatalog-diff -d -n SomeNodeName.yourdomain.com
```
### Run only certain components of the command
To perform the bootstrapping and catalog compilation in separate steps, you can run octocatalog-diff with arguments asking it to do only one or the other. This will help you narrow down whether the problem is in the bootstrapping (first command) or catalog compilation (second command).
Be sure you are in the directory where your Puppet code is checked out when you run these commands.
To run just the bootstrapping code (do this within a checkout of your Puppet repository):
```
mkdir /tmp/octo-test
octocatalog-diff -d --bootstrap-then-exit --bootstrapped-from-dir=/tmp/octo-test
```
To run just the catalog compilation code (do this within a checkout of your Puppet repository):
```
octocatalog-diff -d -n SomeNodeName.yourdomain.com -o /tmp/catalog.json --bootstrapped-to-dir=$PWD --catalog-only
```
### Contact us
Still having trouble? Please [open an issue](https://github.com/github/octocatalog-diff/issues/new) and we will do our best to help.
Please follow the provided issue template, which will ask you for certain output that we need to diagnose the problem.
octocatalog-diff-2.1.0/doc/versions/ 0000775 0000000 0000000 00000000000 14341123201 0017323 5 ustar 00root root 0000000 0000000 octocatalog-diff-2.1.0/doc/versions/v1.md 0000664 0000000 0000000 00000002764 14341123201 0020204 0 ustar 00root root 0000000 0000000 # What's new in octocatalog-diff 1.0
#### Summary
The most significant change in version 1.0 is the addition of the 
`octocatalog-diff` is a tool that enables developers to be more efficient when testing changes to Puppet manifests. It is most commonly used to display differences in Puppet catalogs between stable and development branches. It does not require a working Puppet master (or puppetserver), so it is often run by developers on their workstations and in Continuous Integration environments.
At GitHub, we manage thousands of nodes with a Puppet code base containing 500,000+ lines of code from over 200 contributors. We run `octocatalog-diff` thousands of times per day as part of Continuous Integration testing, and developers run it on their workstations as they are working with the code.
`octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
We consider the 1.x release of `octocatalog-diff` to be stable and production-quality. We continue to maintain and enhance `octocatalog-diff` to meet GitHub's internal needs and to incorporate suggestions from the community. Please consult the [change log](/doc/CHANGELOG.md) for details.
If you've been using version 0.6.1 or earlier, please read about [What's new in octocatalog-diff 1.0](/doc/versions/v1.md) for a summary of new capabilities and breaking changes.
## How?
Traditional Puppet development generally takes one of two forms. Frequently, developers will test changes by running a Puppet agent (perhaps in `--noop` mode) to see if the desired change has resulted on an actual system. Others will use formal testing methodologies, such as `rspec-puppet` or the beaker framework to validate Puppet code.
`octocatalog-diff` uses a different pattern. In its most common invocation, it compiles Puppet catalogs for both the stable branch (e.g. master) and the development branch, and then compares them. It filters out attributes or resources that have no effect on ultimate state of the target system (e.g. tags) and displays the remaining differences. Using this strategy, one can get feedback on changes without deploying Puppet code to a server and conducting a full Puppet run, and this tool works even if test coverage is incomplete.
There are some [limitations](doc/limitations.md) to a catalog-based approach, meaning it will never completely replace unit, integration, or deployment testing. However, it does provide substantial time savings in both the development and testing cycle. In this repository, we provide example scripts for using `octocatalog-diff` in development and CI environments.
`octocatalog-diff` is currently able to get catalogs by the following methods:
- Compile catalog via the command line with a Puppet agent on your machine (as GitHub uses the tool internally)
- Obtain catalog over the network from PuppetDB
- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x through 6.x supported)
- Read catalog from a JSON file
## Example
Here is simulated output from running `octocatalog-diff` to compare the Puppet catalog changes between the master branch and the Puppet code in the current working directory:
![[octocatalog-diff screenshot]](doc/images/screenshot1.png)
The example above reflects the changes in the Puppet catalog from switching an underlying device for a mounted file system.
## Documentation
### Installation and use in a development environment
- [Installation](/doc/installation.md)
- [Configuration](/doc/configuration.md)
- [Basic command line usage](/doc/basic.md)
- [Advanced command line usage](/doc/advanced.md)
- [Troubleshooting](/doc/troubleshooting.md)
### Installation and use for CI
- [Setting up octocatalog-diff in CI](/doc/advanced-ci.md)
### Technical details
- [Requirements](/doc/requirements.md)
- [Limitations](/doc/limitations.md)
- [List of all command line options](/doc/optionsref.md)
- [Environment variables](/doc/advanced-environment-variables.md)
### Project
- [Roadmap](/doc/roadmap.md)
- [Similar tools](/doc/similar.md)
- [Contributing](/.github/CONTRIBUTING.md)
- [Developer documentation](/doc/dev)
- [API documentation](/doc/dev/api.md)
## What's in a name?
During its original development at GitHub, this tool was simply called `catalog-diff`. However, there is already a [Puppet module with that name](https://forge.puppet.com/zack/catalog_diff) and we didn't want to create any confusion (in fact, a case could be made to use both approaches). So, we named the tool `octocatalog-diff` because who doesn't like the [octocat](https://octodex.github.com/)? Then one day in chat, someone referred to the tool as ":octocat:alog-diff", and that moniker caught on for electronic communication.
## Contributing
Please see our [contributing document](/.github/CONTRIBUTING.md) if you would like to participate!
## Getting help
If you have a problem or suggestion, please [open an issue](https://github.com/github/octocatalog-diff/issues/new) in this repository, and we will do our best to help. Please note that this project adheres to the [Open Code of Conduct](http://todogroup.org/opencodeofconduct/#GitHub%20Octocatalog-Diff/opensource@github.com).
## License
`octocatalog-diff` is licensed under the [MIT license](LICENSE).
It requires 3rd party ruby gems found [here](/vendor/cache). It also includes portions of other open source projects [here](/lib/octocatalog-diff/external/pson), [here](/spec/octocatalog-diff/fixtures/repos/default/modules/stdlib), [here](/spec/octocatalog-diff/support/httparty) and [here](/spec/octocatalog-diff/tests/external/pson). All 3rd party code and required gems are licensed either as MIT or Apache 2.0.
## Authors / Owners
`octocatalog-diff` was originally designed and authored by [Kevin Paulisse](https://github.com/kpaulisse). It is now maintained by the Site Reliability Engineering team at GitHub.
octocatalog-diff-2.1.0/bin/ 0000775 0000000 0000000 00000000000 14341123201 0015456 5 ustar 00root root 0000000 0000000 octocatalog-diff-2.1.0/bin/octocatalog-diff 0000775 0000000 0000000 00000002505 14341123201 0020613 0 ustar 00root root 0000000 0000000 #!/usr/bin/env ruby
if ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH']
# Mostly used for internal testing, to allow pointing of a "real" octocatalog-diff install
# at code being developed live.
rel = File.expand_path(ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH'], File.dirname(__FILE__))
abs = File.expand_path(ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH'])
if File.directory?(abs) && File.file?(File.join(abs, 'lib', 'octocatalog-diff.rb'))
require File.join(abs, 'lib', 'octocatalog-diff')
elsif File.directory?(rel) && File.file?(File.join(rel, 'lib', 'octocatalog-diff.rb'))
require File.join(rel, 'lib', 'octocatalog-diff')
else
raise Errno::ENOENT, "Unable to resolve #{ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH']} (tried #{abs} then #{rel})"
end
elsif File.file?(File.expand_path('../lib/octocatalog-diff.rb', File.dirname(__FILE__)))
require_relative '../lib/octocatalog-diff'
else
require 'octocatalog-diff'
end
config_test = ARGV.include?('--config-test')
logger = Logger.new(STDERR)
logger.level = Logger::INFO
logger.level = Logger::DEBUG if config_test
options = OctocatalogDiff::API::V1.config(logger: logger, test: config_test)
if config_test
logger.info 'Exiting now because --config-test was specified'
exit(0)
end
argv = ARGV.dup
exit_code = OctocatalogDiff::Cli.cli(argv, Logger.new(STDERR), options)
exit(exit_code)
octocatalog-diff-2.1.0/doc/ 0000775 0000000 0000000 00000000000 14341123201 0015453 5 ustar 00root root 0000000 0000000 octocatalog-diff-2.1.0/doc/CHANGELOG.md 0000664 0000000 0000000 00000026301 14341123201 0017266 0 ustar 00root root 0000000 0000000 # octocatalog-diff change log