Class: AWSCDK::SecretValue

Inherits:
Intrinsic
  • Object
show all
Defined in:
secret_value.rb

Overview

Work with secret values in the CDK.

Constructs that need secrets will declare parameters of type SecretValue.

The actual values of these secrets should not be committed to your repository, or even end up in the synthesized CloudFormation template. Instead, you should store them in an external system like AWS Secrets Manager or SSM Parameter Store, and you can reference them by calling SecretValue.secretsManager() or SecretValue.ssmSecure().

You can use SecretValue.unsafePlainText() to construct a SecretValue from a literal string, but doing so is highly discouraged.

To make sure secret values don't accidentally end up in readable parts of your infrastructure definition (such as the environment variables of an AWS Lambda Function, where everyone who can read the function definition has access to the secret), using secret values directly is not allowed. You must pass them to constructs that accept SecretValue properties, which are guaranteed to use the value only in CloudFormation properties that are write-only.

If you are sure that what you are doing is safe, you can call secretValue.unsafeUnwrap() to access the protected string of the secret value.

(If you are writing something like an AWS Lambda Function and need to access a secret inside it, make the API call to GetSecretValue directly inside your Lamba's code, instead of using environment variables.)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(protected_value, options = nil) ⇒ SecretValue

Construct a SecretValue (do not use!).

Do not use the constructor directly: use one of the factory functions on the class instead.

Parameters:



42
43
44
45
46
47
 
# File 'secret_value.rb', line 42

def initialize(protected_value, options = nil)
  options = options.is_a?(Hash) ? ::AWSCDK::IntrinsicProps.new(**options.transform_keys(&:to_sym)) : options
  Jsii::Type.check_type(protected_value, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJhbnkifQ==")), "protectedValue")
  Jsii::Type.check_type(options, JSON.parse(Base64.strict_decode64("eyJmcW4iOiJhd3MtY2RrLWxpYi5JbnRyaW5zaWNQcm9wcyJ9")), "options") unless options.nil?
  Jsii::Object.instance_method(:initialize).bind(self).call(protected_value, options)
end

Class Method Details

.cfn_dynamic_reference(ref) ⇒ AWSCDK::SecretValue

Obtain the secret value through a CloudFormation dynamic reference.

If possible, use SecretValue.ssmSecure or SecretValue.secretsManager directly.

Parameters:

Returns:

  • (AWSCDK::SecretValue) 


68
69
70
71
 
# File 'secret_value.rb', line 68

def self.cfn_dynamic_reference(ref)
  Jsii::Type.check_type(ref, JSON.parse(Base64.strict_decode64("eyJmcW4iOiJhd3MtY2RrLWxpYi5DZm5EeW5hbWljUmVmZXJlbmNlIn0=")), "ref")
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "cfnDynamicReference", [ref])
end

.cfn_dynamic_reference_key(secret_id, options = nil) ⇒ String

Returns a key which can be used within an AWS CloudFormation dynamic reference to dynamically load a secret from AWS Secrets Manager.

Parameters:

Returns:

  • (String)

See Also:



79
80
81
82
83
84
 
# File 'secret_value.rb', line 79

def self.cfn_dynamic_reference_key(secret_id, options = nil)
  Jsii::Type.check_type(secret_id, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "secretId")
  options = options.is_a?(Hash) ? ::AWSCDK::SecretsManagerSecretOptions.new(**options.transform_keys(&:to_sym)) : options
  Jsii::Type.check_type(options, JSON.parse(Base64.strict_decode64("eyJmcW4iOiJhd3MtY2RrLWxpYi5TZWNyZXRzTWFuYWdlclNlY3JldE9wdGlvbnMifQ==")), "options") unless options.nil?
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "cfnDynamicReferenceKey", [secret_id, options])
end

.cfn_parameter(param) ⇒ AWSCDK::SecretValue

Obtain the secret value through a CloudFormation parameter.

Generally, this is not a recommended approach. AWS Secrets Manager is the recommended way to reference secrets.

Parameters:

Returns:

  • (AWSCDK::SecretValue) 


93
94
95
96
 
# File 'secret_value.rb', line 93

def self.cfn_parameter(param)
  Jsii::Type.check_type(param, JSON.parse(Base64.strict_decode64("eyJmcW4iOiJhd3MtY2RrLWxpYi5DZm5QYXJhbWV0ZXIifQ==")), "param")
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "cfnParameter", [param])
end

.is_secret_value(x) ⇒ Boolean

Test whether an object is a SecretValue.

Parameters:

  • x (Object)

Returns:

  • (Boolean) 


102
103
104
105
 
# File 'secret_value.rb', line 102

def self.is_secret_value(x)
  Jsii::Type.check_type(x, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJhbnkifQ==")), "x")
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "isSecretValue", [x])
end

.jsii_overridable_methods ⇒ Object 



49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'secret_value.rb', line 49

def self.jsii_overridable_methods
  {
    :creation_stack => { kind: :property, name: "creationStack", is_optional: false },
    :type_hint => { kind: :property, name: "typeHint", is_optional: true },
    :new_error => { kind: :method, name: "newError", is_optional: false },
    :resolve => { kind: :method, name: "resolve", is_optional: false },
    :to_json => { kind: :method, name: "toJSON", is_optional: false },
    :to_string => { kind: :method, name: "toString", is_optional: false },
    :to_string_list => { kind: :method, name: "toStringList", is_optional: false },
    :unsafe_unwrap => { kind: :method, name: "unsafeUnwrap", is_optional: false },
  }
end

.plain_text(secret) ⇒ AWSCDK::SecretValue

Deprecated.

Use unsafePlainText() instead.

Construct a literal secret value for use with secret-aware constructs.

Do not use this method for any secrets that you care about! The value will be visible to anyone who has access to the CloudFormation template (via the AWS Console, SDKs, or CLI).

The only reasonable use case for using this method is when you are testing.

Parameters:

  • secret (String)

Returns:

  • (AWSCDK::SecretValue) 


118
119
120
121
 
# File 'secret_value.rb', line 118

def self.plain_text(secret)
  Jsii::Type.check_type(secret, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "secret")
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "plainText", [secret])
end

.resource_attribute(attr) ⇒ AWSCDK::SecretValue

Use a resource's output as secret value.

Parameters:

  • attr (String)

Returns:

  • (AWSCDK::SecretValue) 


127
128
129
130
 
# File 'secret_value.rb', line 127

def self.resource_attribute(attr)
  Jsii::Type.check_type(attr, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "attr")
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "resourceAttribute", [attr])
end

.secrets_manager(secret_id, options = nil) ⇒ AWSCDK::SecretValue

Creates a SecretValue with a value which is dynamically loaded from AWS Secrets Manager.

If you rotate the value in the Secret, you must also change at least one property on the resource where you are using the secret, to force CloudFormation to re-read the secret.

Parameters:

Returns:

  • (AWSCDK::SecretValue) 


140
141
142
143
144
145
 
# File 'secret_value.rb', line 140

def self.secrets_manager(secret_id, options = nil)
  Jsii::Type.check_type(secret_id, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "secretId")
  options = options.is_a?(Hash) ? ::AWSCDK::SecretsManagerSecretOptions.new(**options.transform_keys(&:to_sym)) : options
  Jsii::Type.check_type(options, JSON.parse(Base64.strict_decode64("eyJmcW4iOiJhd3MtY2RrLWxpYi5TZWNyZXRzTWFuYWdlclNlY3JldE9wdGlvbnMifQ==")), "options") unless options.nil?
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "secretsManager", [secret_id, options])
end

.ssm_secure(parameter_name, version = nil) ⇒ AWSCDK::SecretValue

Use a secret value stored from a Systems Manager (SSM) parameter.

This secret source in only supported in a limited set of resources and properties. Click here for the list of supported properties.

Parameters:

  • parameter_name (String) —

    The name of the parameter in the Systems Manager Parameter Store.

  • version (String, nil) (defaults to: nil) —

    An integer that specifies the version of the parameter to use.

Returns:

  • (AWSCDK::SecretValue) 


156
157
158
159
160
 
# File 'secret_value.rb', line 156

def self.ssm_secure(parameter_name, version = nil)
  Jsii::Type.check_type(parameter_name, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "parameterName")
  Jsii::Type.check_type(version, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "version") unless version.nil?
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "ssmSecure", [parameter_name, version])
end

.unsafe_plain_text(secret) ⇒ AWSCDK::SecretValue

Construct a literal secret value for use with secret-aware constructs.

Do not use this method for any secrets that you care about! The value will be visible to anyone who has access to the CloudFormation template (via the AWS Console, SDKs, or CLI).

The primary use case for using this method is when you are testing.

The other use case where this is appropriate is when constructing a JSON secret. For example, a JSON secret might have multiple fields where only some are actual secret values.

Examples:

secret = nil # AWSCDK::SecretValue

json_secret = {
    username: AWSCDK::SecretValue.unsafe_plain_text("myUsername"),
    password: secret,
}

Parameters:

  • secret (String)

Returns:

  • (AWSCDK::SecretValue) 


183
184
185
186
 
# File 'secret_value.rb', line 183

def self.unsafe_plain_text(secret)
  Jsii::Type.check_type(secret, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "secret")
  Jsii::Kernel.instance.call_static("aws-cdk-lib.SecretValue", "unsafePlainText", [secret])
end

Instance Method Details

#creation_stack ⇒ Array<String>

The captured stack trace which represents the location in which this token was created.

Returns:

  • (Array<String>) 


191
192
193
 
# File 'secret_value.rb', line 191

def creation_stack()
  jsii_get_property("creationStack")
end

#new_error(message) ⇒ Object

Creates a throwable Error object that contains the token creation stack trace.

Parameters:

  • message (String) —

    Error message.

Returns:

  • (Object) 


206
207
208
209
 
# File 'secret_value.rb', line 206

def new_error(message)
  Jsii::Type.check_type(message, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "message")
  jsii_call_method("newError", [message])
end

#resolve(context) ⇒ Object

Resolve the secret.

If the feature flag is not set, resolve as normal. Otherwise, throw a descriptive error that the usage guard is missing.

Parameters:

Returns:

  • (Object) 


218
219
220
221
 
# File 'secret_value.rb', line 218

def resolve(context)
  Jsii::Type.check_type(context, JSON.parse(Base64.strict_decode64("eyJmcW4iOiJhd3MtY2RrLWxpYi5JUmVzb2x2ZUNvbnRleHQifQ==")), "context")
  jsii_call_method("resolve", [context])
end

#to_json ⇒ Object

Turn this Token into JSON.

Called automatically when JSON.stringify() is called on a Token.

Returns:

  • (Object) 


228
229
230
 
# File 'secret_value.rb', line 228

def to_json()
  jsii_call_method("toJSON", [])
end

#to_string ⇒ String

Convert an instance of this Token to a string.

This method will be called implicitly by language runtimes if the object is embedded into a string. We treat it the same as an explicit stringification.

Returns:

  • (String) 


239
240
241
 
# File 'secret_value.rb', line 239

def to_string()
  jsii_call_method("toString", [])
end

#to_string_list ⇒ Array<String>

Convert an instance of this Token to a string list.

This method will be called implicitly by language runtimes if the object is embedded into a list. We treat it the same as an explicit stringification.

Returns:

  • (Array<String>) 


250
251
252
 
# File 'secret_value.rb', line 250

def to_string_list()
  jsii_call_method("toStringList", [])
end

#type_hint ⇒ AWSCDK::ResolutionTypeHint?

Type that the Intrinsic is expected to evaluate to.

Returns:



198
199
200
 
# File 'secret_value.rb', line 198

def type_hint()
  jsii_get_property("typeHint")
end

#unsafe_unwrap ⇒ String

Disable usage protection on this secret.

Call this to indicate that you want to use the secret value held by this object in an unchecked way. If you don't call this method, using the secret value directly in a string context or as a property value somewhere will produce an error.

This method has 'unsafe' in the name on purpose! Make sure that the construct property you are using the returned value in is does not end up in a place in your AWS infrastructure where it could be read by anyone unexpected.

When in doubt, don't call this method and only pass the object to constructs that accept SecretValue parameters.

Returns:

  • (String) 


270
271
272
 
# File 'secret_value.rb', line 270

def unsafe_unwrap()
  jsii_call_method("unsafeUnwrap", [])
end