From bcfb104414feea810f7a1a23563c60597de3ce40 Mon Sep 17 00:00:00 2001 From: Ian Maddaus Date: Mon, 20 Nov 2023 13:20:36 -0500 Subject: [PATCH 1/3] rewrite infra DSL secrets page Signed-off-by: Ian Maddaus --- content/infra_language/secrets.md | 157 ++++++++++++++++++++++-------- 1 file changed, 117 insertions(+), 40 deletions(-) diff --git a/content/infra_language/secrets.md b/content/infra_language/secrets.md index a424778834..b5f8a24ecb 100644 --- a/content/infra_language/secrets.md +++ b/content/infra_language/secrets.md @@ -11,128 +11,205 @@ 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: '', version: '', service: , config: {key: value}) +``` + +Replace the following: + +`` +: 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 + +`` +: 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'}`. + +### 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() +default_secret_config(key: "value") + +value1 = secret(name: "") +value2 = secret(name: "") +value3 = secret(name: "") ``` -#### 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() do + with_secret_config(key: "value") do + value1 = secret(name: "") + value2 = secret(name: "") + value3 = secret(name: "") + end +end ``` -### Akeyless Vault +## Examples -The secrets helper supports fetching secrets from Akeyless Vault using Akeyless' access key and access ID. +### Akeyless Vault -#### Fetching Secrets From Akeyless Vault Using Access Key/ID +Fetch secrets from Akeyless Vault using the access key and access ID: ```ruby -secret(name: '/secret/data/my_secret', +secret(name: '', service: :akeyless_vault, config: { - access_key: '12345678910=', - access_id: 'p-12345678910' + access_key: '', + access_id: '' }) ``` +### AWS Secrets Manager + +Fetch a secret from AWS Secrets Manager: + +```ruby +secret(name: '', service: :aws_secrets_manager) +``` + +Specify an AWS region: + +```ruby +secret(name: '', service: :aws_secrets_manager, config: { region: '' }) +``` + ### Azure Key Vault -The secrets helper supports fetching secrets from Azure Key Vault. +Fetch secrets from Azure Key Vault: + +```ruby +secret(name: '', service: :azure_key_vault) +``` + +Specify the vault name in the config: + +```ruby +secret(name: '', service: :azure_key_vault, config: { vault: '' }) +``` -#### Fetching Secrets From Azure Key Vault +Fetch a specific version of an Azure Key Vault secret: ```ruby -secret(name: 'vault-name/test-secret-1', service: :azure_key_vault) +secret(name: '', version: 'v1', service: :azure_key_vault) ``` -#### Fetching a specific version of an Azure Key Vault secret +Define a default secret service and then fetch multiple secrets from different client IDs: ```ruby -secret(name: 'vault-name/test1', version: 'v1', service: :azure_key_vault) +default_secret_service(:azure_key_vault) + +with_secret_config(client_id: "") do + secret_1 = secret(name: "") + secret_2 = secret(name: "") +end + +with_secret_config(client_id: "") do + secret_3 = secret(name: "") + secret_4 = secret(name: "") +end ``` ### 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: '', service: :hashi_vault, config: { vault_addr: 'vault.example.com', - role_name: 'example-role' + role_name: '' }) ``` -#### Fetching Secrets From HashiCorp Vault Using Tokens +Fetch secrets from HashiCorp Vault using tokens: ```ruby -secret(name: 'secret/example', +secret(name: '', service: :hashi_vault, config: { vault_addr: 'vault.example.com', auth_method: :token, - token: '123456' + token: '' }) ``` -#### 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: '', 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_secret_id: "" }) ``` -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: '', service: :hashi_vault, config: { vault_addr: 'vault.example.com', auth_method: :approle, - approle_name: "my-approle", - token: '123456' + approle_name: "", + token: '' }) ``` -## 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: '', 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 From 6a89de3b3dff240e20cd0668106359596ff4867e Mon Sep 17 00:00:00 2001 From: Ian Maddaus Date: Mon, 20 Nov 2023 15:42:24 -0500 Subject: [PATCH 2/3] linting Signed-off-by: Ian Maddaus --- content/infra_language/secrets.md | 40 +++++++++++++++++-------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/content/infra_language/secrets.md b/content/infra_language/secrets.md index b5f8a24ecb..92189c058b 100644 --- a/content/infra_language/secrets.md +++ b/content/infra_language/secrets.md @@ -27,13 +27,15 @@ Use the following syntax to fetch secrets: secret(name: '', version: '', service: , config: {key: value}) ``` + + Replace the following: `` : 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. +`` +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: @@ -53,6 +55,8 @@ Replace the following: `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'}`. + + ### 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. @@ -81,6 +85,22 @@ with_secret_service() do end ``` +Define a default secret service and then fetch secrets with different configs: + +```ruby +default_secret_service() + +with_secret_config(key: "") do + secret_1 = secret(name: "") + secret_2 = secret(name: "") +end + +with_secret_config(key: "") do + secret_3 = secret(name: "") + secret_4 = secret(name: "") +end +``` + ## Examples ### Akeyless Vault @@ -130,22 +150,6 @@ Fetch a specific version of an Azure Key Vault secret: secret(name: '', version: 'v1', service: :azure_key_vault) ``` -Define a default secret service and then fetch multiple secrets from different client IDs: - -```ruby -default_secret_service(:azure_key_vault) - -with_secret_config(client_id: "") do - secret_1 = secret(name: "") - secret_2 = secret(name: "") -end - -with_secret_config(client_id: "") do - secret_3 = secret(name: "") - secret_4 = secret(name: "") -end -``` - ### HashiCorp Vault Fetch secrets from HashiCorp Vault using AWS IAM: From b977e1a431a550d910628ce1b17789d04f81bbb0 Mon Sep 17 00:00:00 2001 From: Ian Maddaus Date: Mon, 20 Nov 2023 16:30:40 -0500 Subject: [PATCH 3/3] typo Signed-off-by: Ian Maddaus --- content/infra_language/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/infra_language/secrets.md b/content/infra_language/secrets.md index 92189c058b..318cee5d07 100644 --- a/content/infra_language/secrets.md +++ b/content/infra_language/secrets.md @@ -35,7 +35,7 @@ Replace the following: : The identifier or name for this secret. `` -The secret version. If a service supports versions and you don't provide a version, the Secrets Management Integration helper fetches the latest 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: