Merge branch 'main' into patch-2

chef · Nov 28, 2023 · c3eb81d · c3eb81d
2 parents ba2938f + ecd7ccd
commit c3eb81d
Show file tree

Hide file tree

Showing 4 changed files with 125 additions and 44 deletions.
diff --git a/_vendor/modules.txt b/_vendor/modules.txt
@@ -1,7 +1,7 @@
 # github.com/chef/automate/components/docs-chef-io v0.0.0-20231027151655-61e0a5d70b2c
 # github.com/chef/desktop-config/docs-chef-io v0.0.0-20230711052355-bad26ce3ac0b
 # github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20230808222519-d0c20bbe8c45
-# github.com/chef/chef-server/docs-chef-io v0.0.0-20230929110551-e5bebd3e433d
+# github.com/chef/chef-server/docs-chef-io v0.0.0-20231127093116-305bca610b36
 # github.com/inspec/inspec/docs-chef-io v0.0.0-20231116093529-690d036f8af1
 # github.com/inspec/inspec-alicloud/docs-chef-io v0.0.0-20220614123852-e453ba687370
 # github.com/inspec/inspec-aws/docs-chef-io v0.0.0-20220228151600-69aa036b1527

diff --git a/content/infra_language/secrets.md b/content/infra_language/secrets.md
@@ -11,128 +11,209 @@ gh_repo = "chef-web-docs"
     parent = "chef_infra/infra_language"
 +++
 
-The Secrets Management Integration helper is a beta feature starting in Chef Infra Client 17.5 and became a fully supported feature in Chef Infra Client 18. This helper allows you to access secrets from the following secrets management systems within your Infra recipes or resources:
+The Secrets Management Integration helper is a beta feature starting in Chef Infra Client 17.5 and became a fully supported feature in Chef Infra Client 18.
+This helper allows you to access secrets from the following secrets management systems within your Infra recipes or resources:
 
 - AWS Secrets Manager
 - Akeyless Vault
 - Azure Key Vault
 - HashiCorp Vault
 
-## Secrets Manager Support
+## Syntax
 
-### AWS Secrets Manager
+Use the following syntax to fetch secrets:
+
+```ruby
+secret(name: '<SECRET_NAME>', version: '<VERSION>', service: <SERVICE>, config: {key: value})
+```
+
+<!-- markdownlint-disable MD006 MD007 -->
+
+Replace the following:
+
+`<SECRET_NAME>`
+: The identifier or name for this secret.
+
+`<VERSION>`
+: The secret version. If a service supports versions and you don't provide a version, the Secrets Management Integration helper fetches the latest version.
+
+  Secret versions supported with:
+
+  - AWS Secrets Manager
+  - Azure Key Vault
+
+`<SERVICE>`
+: The secret manager.
 
-The secrets helper supports fetching secrets from AWS Secrets Manager from IAM roles applied to instances.
+  Allowed values:
 
-#### Fetching an AWS Secrets Manager secret
+  - `:akeyless_vault`
+  - `:aws_secrets_manager`
+  - `:azure_key_vault`
+  - `:hashi_vault`
+
+`config`
+: Use `config` to set key/value settings passed to a secrets manager. For example, to set the AWS region that a secret is stored in with AWS Secrets Manager, add `config: {region: 'us-west-2'}`.
+
+<!-- markdownlint-enable MD006 MD007 -->
+
+### Set defaults
+
+You can set a default service and service configuration and then the Secrets Management Integration helper will use those settings every time you request a secret.
+This is useful if you want to request more than one secret from the same service.
+
+Use the `default_secret_service` and `default_secret_config` to define a default service and service configuration:
 
 ```ruby
-secret(name: 'test1', service: :aws_secrets_manager)
+default_secret_service(<SERVICE>)
+default_secret_config(key: "value")
+
+value1 = secret(name: "<SECRET_NAME_1>")
+value2 = secret(name: "<SECRET_NAME_2>")
+value3 = secret(name: "<SECRET_NAME_3>")
 ```
 
-#### Specifying the AWS Region containing the secret
+Or wrap your secret definitions using `with_secret_service` and `with_secret_config`:
 
 ```ruby
-secret(name: 'test1', service: :aws_secrets_manager, config: { region: 'us-west-2' })
+with_secret_service(<SERVICE>) do
+  with_secret_config(key: "value") do
+    value1 = secret(name: "<SECRET_NAME_1>")
+    value2 = secret(name: "<SECRET_NAME_2>")
+    value3 = secret(name: "<SECRET_NAME_3>")
+  end
+end
 ```
 
-### Akeyless Vault
+Define a default secret service and then fetch secrets with different configs:
+
+```ruby
+default_secret_service(<SERVICE>)
 
-The secrets helper supports fetching secrets from Akeyless Vault using Akeyless' access key and access ID.
+with_secret_config(key: "<VALUE>") do
+  secret_1 = secret(name: "<SECRET_NAME_1>")
+  secret_2 = secret(name: "<SECRET_NAME_2>")
+end
+
+with_secret_config(key: "<OTHER_VALUE>") do
+  secret_3 = secret(name: "<SECRET_NAME_3>")
+  secret_4 = secret(name: "<SECRET_NAME_4>")
+end
+```
+
+## Examples
 
-#### Fetching Secrets From Akeyless Vault Using Access Key/ID
+### Akeyless Vault
+
+Fetch secrets from Akeyless Vault using the access key and access ID:
 
 ```ruby
-secret(name: '/secret/data/my_secret',
+secret(name: '<SECRET_NAME>',
        service: :akeyless_vault,
        config: {
-         access_key: '12345678910=',
-         access_id: 'p-12345678910'
+         access_key: '<ACCESS_KEY>',
+         access_id: '<ACCESS_ID>'
       })
 ```
 
+### AWS Secrets Manager
+
+Fetch a secret from AWS Secrets Manager:
+
+```ruby
+secret(name: '<SECRET_NAME>', service: :aws_secrets_manager)
+```
+
+Specify an AWS region:
+
+```ruby
+secret(name: '<SECRET_NAME>', service: :aws_secrets_manager, config: { region: '<AWS_REGION>' })
+```
+
 ### Azure Key Vault
 
-The secrets helper supports fetching secrets from Azure Key Vault.
+Fetch secrets from Azure Key Vault:
 
-#### Fetching Secrets From Azure Key Vault
+```ruby
+secret(name: '<VAULT_NAME/SECRET_NAME>', service: :azure_key_vault)
+```
+
+Specify the vault name in the config:
 
 ```ruby
-secret(name: 'vault-name/test-secret-1', service: :azure_key_vault)
+secret(name: '<SECRET_NAME>', service: :azure_key_vault, config: { vault: '<VAULT_NAME>' })
 ```
 
-#### Fetching a specific version of an Azure Key Vault secret
+Fetch a specific version of an Azure Key Vault secret:
 
 ```ruby
-secret(name: 'vault-name/test1', version: 'v1', service: :azure_key_vault)
+secret(name: '<VAULT_NAME/SECRET_NAME>', version: 'v1', service: :azure_key_vault)
 ```
 
 ### HashiCorp Vault
 
-#### Fetching Secrets From HashiCorp Vault Using AWS IAM
+Fetch secrets from HashiCorp Vault using AWS IAM:
 
 ```ruby
-secret(name: 'secret/example',
+secret(name: '<PATH/TO/SECRET>',
       service: :hashi_vault,
       config: {
         vault_addr: 'vault.example.com',
-        role_name: 'example-role'
+        role_name: '<ROLE>'
       })
 ```
 
-#### Fetching Secrets From HashiCorp Vault Using Tokens
+Fetch secrets from HashiCorp Vault using tokens:
 
 ```ruby
-secret(name: 'secret/example',
+secret(name: '<PATH/TO/SECRET>',
       service: :hashi_vault,
       config: {
         vault_addr: 'vault.example.com',
         auth_method: :token,
-        token: '123456'
+        token: '<TOKEN_STRING>'
       })
 ```
 
-#### Fetching Secrets From HashiCorp Vault Using AppRole Authentication
-
-Fetching secret data using an AppRole ID and an associated AppRole Secret ID:
+Fetch secrets from HashiCorp Vault using AppRole ID and an associated AppRole Secret ID:
 
 ```ruby
-secret(name: 'secret/example',
+secret(name: '<PATH/TO/SECRET>',
       service: :hashi_vault,
       config: {
         vault_addr: 'vault.example.com',
         auth_method: :approle,
-        approle_id: "11111111-abcd-1111-abcd-111111111111",
-        approle_secret_id: "22222222-abcd-2222-abcd-222222222222"
+        approle_id: "<APPROLE_ID_STRING>",
+        approle_secret_id: "<APPROLE_SECRET_ID_STRING>"
       })
 ```
 
-Fetching secret data using a token and an AppRole name creates a Secret ID associated with that AppRole:
+Fetch secrets using a token and an AppRole name creates a Secret ID associated with that AppRole:
 
 ```ruby
-secret(name: 'secret/example',
+secret(name: '<PATH/TO/SECRET>',
       service: :hashi_vault,
       config: {
         vault_addr: 'vault.example.com',
         auth_method: :approle,
-        approle_name: "my-approle",
-        token: '123456'
+        approle_name: "<APPROLE_NAME>",
+        token: '<TOKEN_STRING>'
       })
 ```
 
-## Using in Cookbooks
+### Fetch secrets in cookbooks
 
-The secrets helper returns a text string, so it can be used anywhere in Chef Infra where you might hard code a value or access a value from a data bag.
+The secrets helper returns a text string, so you can use it anywhere in Chef Infra where you might hard code a value or access a value from a data bag.
 
-### Writing a Secret To a File
+Write a secret to a file:
 
 ```ruby
 file '/home/ubuntu/aws-secret' do
-  content secret(name: 'test1', service: :aws_secrets_manager)
+  content secret(name: '<SECRET_NAME>', service: :aws_secrets_manager)
 end
 ```
 
-### Passing a Secret to a Template
+Pass a secret to a template:
 
 ```ruby
 template '/etc/my_fancy_service/my_fancy_service.conf' do

diff --git a/go.mod b/go.mod
@@ -4,7 +4,7 @@ go 1.18
 
 require (
 	github.com/chef/automate/components/docs-chef-io v0.0.0-20231027151655-61e0a5d70b2c // indirect
-	github.com/chef/chef-server/docs-chef-io v0.0.0-20230929110551-e5bebd3e433d // indirect
+	github.com/chef/chef-server/docs-chef-io v0.0.0-20231127093116-305bca610b36 // indirect
 	github.com/chef/chef-workstation/docs-chef-io v0.0.0-20230906065503-8f1a978813f8 // indirect
 	github.com/chef/compliance-profiles/docs-chef-io v0.0.0-20231031143423-5ffd549d4a19 // indirect
 	github.com/chef/compliance-remediation-2022/docs-chef-io v0.0.0-20230809063034-95b117807a75 // indirect

diff --git a/go.sum b/go.sum
@@ -3,8 +3,8 @@ github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/chef/automate/components/docs-chef-io v0.0.0-20231027151655-61e0a5d70b2c h1:qp3KGGBgifLcQFbci1bzNDNI8qoIwVLvRCuvSfzuCPI=
 github.com/chef/automate/components/docs-chef-io v0.0.0-20231027151655-61e0a5d70b2c/go.mod h1:juvLC7Rt33YOCgJ5nnfl4rWZRAbSwqjTbWmcAoA0LtU=
-github.com/chef/chef-server/docs-chef-io v0.0.0-20230929110551-e5bebd3e433d h1:e9VRN2RQee3ali2dcqvkIhSf1UaL8vFNg70Hs1ZnBWE=
-github.com/chef/chef-server/docs-chef-io v0.0.0-20230929110551-e5bebd3e433d/go.mod h1:gMSa25GUHmLimA0gjvRd3hs1buOBqkKPrdHzHvaJauY=
+github.com/chef/chef-server/docs-chef-io v0.0.0-20231127093116-305bca610b36 h1:yognvfb/VxihujSLSPmu3mFZ+fXgzDv/L4+84W9TA1o=
+github.com/chef/chef-server/docs-chef-io v0.0.0-20231127093116-305bca610b36/go.mod h1:gMSa25GUHmLimA0gjvRd3hs1buOBqkKPrdHzHvaJauY=
 github.com/chef/chef-workstation/docs-chef-io v0.0.0-20230906065503-8f1a978813f8 h1:rMpqWWnaV+fzB5Qk+8sNdbMgBarjPmCGSF623V5SOqc=
 github.com/chef/chef-workstation/docs-chef-io v0.0.0-20230906065503-8f1a978813f8/go.mod h1:gvoh6ov1YU98CVzBEWzEZeCLTRunfQ6r1VO7M3LFE9U=
 github.com/chef/compliance-profiles/docs-chef-io v0.0.0-20231031143423-5ffd549d4a19 h1:EH5D0WGIvEi2m87pSHKdQPXCuiVrBHcyIenonB3YpTM=