summaryrefslogtreecommitdiff
path: root/DOC_CHANGES.md
diff options
context:
space:
mode:
authortyler-ball <tyleraball@gmail.com>2014-09-16 10:09:07 -0700
committertyler-ball <tyleraball@gmail.com>2014-09-29 08:31:08 -0700
commit4f3674c03c874afe9e0dab6f02073edac0873db9 (patch)
tree6450d1febbc9df5b53dc63c164205bdefd06570c /DOC_CHANGES.md
parent32310137000ca0983f3952eb3febb08c93c84bdc (diff)
downloadchef-4f3674c03c874afe9e0dab6f02073edac0873db9.tar.gz
Updating documentation for new data bag UX - providing examples and explanation
Diffstat (limited to 'DOC_CHANGES.md')
-rw-r--r--DOC_CHANGES.md36
1 files changed, 36 insertions, 0 deletions
diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index 29fca72484..b79e06b4fc 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -90,6 +90,42 @@ DSL method `data_bag_item` now takes an optional String parameter `secret`, whic
If the data bag item being fetched is encrypted and no `secret` is provided, Chef looks for a secret at `Chef::Config[:encrypted_data_bag_secret]`.
If `secret` is provided, but the data bag item is not encrypted, then a regular data bag item is returned (no decryption is attempted).
+### Encrypted data bag UX
+The user can now provide a secret for data bags in 4 ways. They are, in order of descending preference:
+1. Provide the secret on the command line of `knife data bag` and `knife bootstrap` commands with `--secret`
+1. Provide the location of a file containing the secret on the command line of `knife data bag` and `knife bootstrap` commands with `--secret-file`
+1. Add the secret to your workstation config with `knife[:secret] = ...`
+1. Add the location of a file containing the secret to your workstation config with `knife[:secret-file] = ...`
+
+When adding the secret information to your workstation config, it will not be used for writeable operations unless `--encrypt` is also passed on the command line.
+Data bag read-only operations (`knife data bag show` and `knife bootstrap`) do not require `--encrypt` to be passed, and will attempt to use an available secret for decryption.
+Unencrypted data bags will not attempt to be unencrypted, even if a secret is provided.
+Trying to view an encrypted data bag without providing a secret will issue a warning and show the encrypted contents.
+Trying to edit or create an encrypted data bag without providing a secret will fail.
+
+Here are some example scenarios:
+
+```
+# Providing `knife[:secret_file] = ...` in knife.rb will create and encrypt the data bag
+knife data bag create BAG_NAME ITEM_NAME --encrypt
+
+# The same command ran with --secret will use the command line secret instead of the knife.rb secret
+knife data bag create ANOTHER_BAG ITEM_NAME --encrypt --secret 'ANOTHER_SECRET'
+
+# The next two commands will fail, because they are using the wrong secret
+knife data bag edit BAG_NAME --secret 'ANOTHER_SECRET'
+knife data bag edit ANOTHER_BAG --encrypt
+
+# The next command will unencrypt the data and show it using the `knife[:secret_file]` without passing the --encrypt flag
+knife data bag show BAG_NAME
+
+# To create an unencrypted data bag, simply do not provide `--secret`, `--secret-file` or `--encrypt`
+knife data bag create UNENCRYPTED_BAG
+
+# If a secret is available from any of the 4 possible entries, it will be copied to a bootstrapped node, even if `--encrypt` is not present
+knife bootstrap FQDN
+```
+
### Enhanced search functionality: result filtering
#### Use in recipes
`Chef::Search::Query#search` can take an optional `:filter_result` argument which returns search data in the form of the Hash specified. Suppose your data looks like