/usr/share/doc/octocatalog-diff/advanced-override-facts.md is in octocatalog-diff 1.5.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 | # Overriding facts
One powerful feature of `octocatalog-diff` allows you to override facts when compiling the catalogs, to predict the effect of a fact change on the catalog. This is useful to simulate a change in agent node configuration without actually setting up an agent to do so.
## Usage
To override a fact in the "to" catalog:
```
--to-fact-override factname=value
```
To override a fact in the "from" catalog:
```
--from-fact-override factname=value
```
You may use as many of these arguments as you wish to adjust as many facts as you wish.
## Examples
Simulate a change to its IP address in the "to" branch:
```
octocatalog-diff -n some-node.example.com -f master -t master \
--to-fact-override ipaddress=10.0.0.1
```
Simulate a change in operating system version (in this case, from Ubuntu trusty to xenial):
```
octocatalog-diff -n some-node.example.com -f master -t master \
--from-fact-override lsbdistcodename=trusty --to-fact-override lsbdistcodename=xenial
```
Simulate changes to multiple facts, in this case the effect of moving a physical machine into EC2:
```
octocatalog-diff -n some-node.example.com -f master -t master \
--to-fact-override ec2=true --to-fact-override ec2_ami_id=ami-abcdef01 \
--to-fact-override ec2_hostname=ip-172-16-0-1.internal --to-fact-override ec2_instance_id=i-ba987654 \
--to-fact-override ec2_instance_type=c4.2xlarge ...... \
--to-fact-override virtual=xenhvm
```
Note that each of the examples specified the from branch and to branch to be `master`. There is no requirement that you do this, but you can generally obtain the most accurate test results by changing only one variable at a time.
## Advanced usage
The `octocatalog-diff` parser will attempt to guess the data type based on the input. However, you can force the data type using the following syntax:
```
octocatalog-diff -n some-node.example.com -f master -t master \
--to-fact-override some_fact='(string)42' fact_to_delete='(nil)'
```
The following data types in parentheses are supported:
| Data type in parentheses | Description |
| ------------------------ | ------------|
| `(string)` | Treat the input as a string |
| `(fixnum)` | Treat the input as an integer (calls the `.to_i` method in ruby) |
| `(float)` | Treat the input as an integer (calls the `.to_f` method in ruby) |
| `(json)` | Treat the input as a JSON string (calls `JSON.parse` in ruby) |
| `(boolean)` | Treat the input as a boolean -- it must be `true` or `false`, case-insensitive |
| `(nil)` | Ignore any characters after `(nil)` and deletes the fact if the fact exists |
## Regular expressions
If you wish to match multiple facts by pattern, specify the regular expression in place of the key name. For example:
```
octocatalog-diff -n some-node.example.com -f master -t master \
--to-fact-override /^ipaddress/=10.11.12.13
```
In this example, `$::ipaddress`, `$::ipaddress_eth0`, `$::ipaddress_bond0`, and any other facts starting with "ipaddress" would be overridden. However, a fact named `$::additional_ipaddress` would not be overridden, because it does not match the regular expression.
Please note that you cannot *add* a fact with a regular expression -- when using regular expressions you can only modify or delete facts.
|