CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com-pulumi-pulumi-aws-sdk-v7

A Pulumi provider SDK for creating and managing Amazon Web Services (AWS) cloud resources in Go, providing strongly-typed resource classes and data sources for all major AWS services.

Overview
Eval results
Files

kms.mddocs/reference/iam-security/

KMS and Secrets Manager Packages

KMS Package

Package import path: github.com/pulumi/pulumi-aws/sdk/v7/go/aws/kms

import "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/kms"

Overview

The KMS package provides resources and data sources to manage AWS Key Management Service (KMS) customer-managed keys (CMKs), aliases, grants, and key policies. KMS keys are used to encrypt data at rest across AWS services.

Resource and Data Source Index

Resources (New*)

  • NewAlias - Friendly name alias for a KMS key
  • NewCiphertext - Encrypted ciphertext using a KMS key
  • NewCustomKeyStore - Custom key store backed by CloudHSM
  • NewExternalKey - KMS key with external key material
  • NewGrant - KMS grant for cross-account or fine-grained access
  • NewKey - KMS customer-managed key (CMK)
  • NewKeyPolicy - Standalone key policy for a KMS key
  • NewReplicaExternalKey - Multi-region replica of an external key
  • NewReplicaKey - Multi-region replica key

Data Sources (Get*/Lookup*)

  • LookupKey - Look up a KMS key by ID, ARN, or alias
  • GetAlias - Look up a KMS alias
  • GetCiphertext - Encrypt plaintext using a KMS key
  • GetCustomKeyStore - Look up a custom key store
  • GetPublicKey - Get the public key of an asymmetric KMS key

Resource: Key

Manages a single-Region or multi-Region primary KMS customer-managed key.

NOTE: KMS Key Policy can be configured either in this resource via the Policy field, or in the standalone kms.KeyPolicy resource. Do not configure both simultaneously.

func NewKey(ctx *pulumi.Context,
    name string, args *KeyArgs, opts ...pulumi.ResourceOption) (*Key, error)

func GetKey(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *KeyState, opts ...pulumi.ResourceOption) (*Key, error)

KeyArgs

type KeyArgs struct {
    // Flag to bypass the key policy lockout safety check.
    // Setting true increases risk of key becoming unmanageable. Default false.
    BypassPolicyLockoutSafetyCheck pulumi.BoolPtrInput

    // ID of the KMS Custom Key Store where the key will be stored (e.g., CloudHSM).
    CustomKeyStoreId pulumi.StringPtrInput

    // Key spec - symmetric or asymmetric.
    // Valid values: SYMMETRIC_DEFAULT, RSA_2048, RSA_3072, RSA_4096,
    //   HMAC_224, HMAC_256, HMAC_384, HMAC_512,
    //   ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, ECC_SECG_P256K1,
    //   ML_DSA_44, ML_DSA_65, ML_DSA_87, SM2 (China only), ECC_NIST_EDWARDS25519.
    // Defaults to SYMMETRIC_DEFAULT.
    CustomerMasterKeySpec pulumi.StringPtrInput

    // Waiting period in days before deletion (7-30). Defaults to 30.
    DeletionWindowInDays pulumi.IntPtrInput

    // Description of the key as viewed in AWS console.
    Description pulumi.StringPtrInput

    // Whether key rotation is enabled. Defaults to false.
    EnableKeyRotation pulumi.BoolPtrInput

    // Whether the key is enabled. Defaults to true.
    IsEnabled pulumi.BoolPtrInput

    // Intended use of the key.
    // Valid values: ENCRYPT_DECRYPT, SIGN_VERIFY, GENERATE_VERIFY_MAC.
    // Defaults to ENCRYPT_DECRYPT.
    KeyUsage pulumi.StringPtrInput

    // Whether this is a multi-Region key. Defaults to false.
    MultiRegion pulumi.BoolPtrInput

    // Valid policy JSON document. Can use iam.GetPolicyDocument to generate.
    // NOTE: If not specified, AWS assigns a default key policy granting all account
    // principals unlimited access to all KMS operations.
    Policy pulumi.StringPtrInput

    // AWS region for this resource. Defaults to provider region.
    Region pulumi.StringPtrInput

    // Custom rotation period in days (90-2560).
    RotationPeriodInDays pulumi.IntPtrInput

    // Key-value map of tags.
    Tags pulumi.StringMapInput

    // Identifies the external key that serves as key material (for external key stores).
    XksKeyId pulumi.StringPtrInput
}

Key (Output Fields)

type Key struct {
    pulumi.CustomResourceState

    // ARN of the key.
    Arn pulumi.StringOutput `pulumi:"arn"`

    BypassPolicyLockoutSafetyCheck pulumi.BoolPtrOutput   `pulumi:"bypassPolicyLockoutSafetyCheck"`
    CustomKeyStoreId               pulumi.StringPtrOutput `pulumi:"customKeyStoreId"`
    CustomerMasterKeySpec          pulumi.StringPtrOutput `pulumi:"customerMasterKeySpec"`
    DeletionWindowInDays           pulumi.IntPtrOutput    `pulumi:"deletionWindowInDays"`
    Description                    pulumi.StringOutput    `pulumi:"description"`
    EnableKeyRotation               pulumi.BoolPtrOutput   `pulumi:"enableKeyRotation"`
    IsEnabled                      pulumi.BoolPtrOutput   `pulumi:"isEnabled"`

    // The globally unique identifier for the key.
    KeyId pulumi.StringOutput `pulumi:"keyId"`

    KeyUsage             pulumi.StringPtrOutput `pulumi:"keyUsage"`
    MultiRegion          pulumi.BoolOutput      `pulumi:"multiRegion"`
    Policy               pulumi.StringOutput    `pulumi:"policy"`
    Region               pulumi.StringOutput    `pulumi:"region"`
    RotationPeriodInDays pulumi.IntOutput       `pulumi:"rotationPeriodInDays"`
    Tags                 pulumi.StringMapOutput `pulumi:"tags"`
    TagsAll              pulumi.StringMapOutput `pulumi:"tagsAll"`
    XksKeyId             pulumi.StringPtrOutput `pulumi:"xksKeyId"`
}

Usage Examples

Symmetric Encryption Key (most common):

import (
    "encoding/json"
    "fmt"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/kms"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

current, err := aws.GetCallerIdentity(ctx, nil, nil)

keyPolicy, err := json.Marshal(map[string]interface{}{
    "Version": "2012-10-17",
    "Statement": []map[string]interface{}{
        {
            "Sid":    "Enable IAM User Permissions",
            "Effect": "Allow",
            "Principal": map[string]interface{}{
                "AWS": fmt.Sprintf("arn:aws:iam::%s:root", current.AccountId),
            },
            "Action":   "kms:*",
            "Resource": "*",
        },
    },
})

key, err := kms.NewKey(ctx, "myKey", &kms.KeyArgs{
    Description:          pulumi.String("My encryption key"),
    EnableKeyRotation:    pulumi.Bool(true),
    DeletionWindowInDays: pulumi.Int(10),
    Policy:               pulumi.String(string(keyPolicy)),
    Tags: pulumi.StringMap{
        "Environment": pulumi.String("prod"),
    },
})

Asymmetric RSA Key for signing:

key, err := kms.NewKey(ctx, "signingKey", &kms.KeyArgs{
    Description:           pulumi.String("RSA signing key"),
    CustomerMasterKeySpec: pulumi.String("RSA_3072"),
    KeyUsage:              pulumi.String("SIGN_VERIFY"),
    EnableKeyRotation:     pulumi.Bool(false), // asymmetric keys cannot auto-rotate
})

Multi-Region primary key:

key, err := kms.NewKey(ctx, "primaryKey", &kms.KeyArgs{
    Description:          pulumi.String("Multi-region primary key"),
    MultiRegion:          pulumi.Bool(true),
    EnableKeyRotation:    pulumi.Bool(true),
    DeletionWindowInDays: pulumi.Int(7),
})

Resource: Alias

Provides a friendly name alias for a KMS key. Aliases must start with alias/.

func NewAlias(ctx *pulumi.Context,
    name string, args *AliasArgs, opts ...pulumi.ResourceOption) (*Alias, error)

func GetAlias(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *AliasState, opts ...pulumi.ResourceOption) (*Alias, error)

AliasArgs

type AliasArgs struct {
    // Display name of the alias. Must start with "alias/".
    // Conflicts with NamePrefix.
    Name pulumi.StringPtrInput

    // Creates a unique alias with the specified prefix. Must start with "alias/".
    // Conflicts with Name.
    NamePrefix pulumi.StringPtrInput

    // AWS region for this resource.
    Region pulumi.StringPtrInput

    // Identifier for the key: ARN or key_id.
    TargetKeyId pulumi.StringInput
}

Alias (Output Fields)

type Alias struct {
    pulumi.CustomResourceState

    // ARN of the key alias.
    Arn pulumi.StringOutput `pulumi:"arn"`

    Name       pulumi.StringOutput `pulumi:"name"`
    NamePrefix pulumi.StringOutput `pulumi:"namePrefix"`
    Region     pulumi.StringOutput `pulumi:"region"`

    // ARN of the target key.
    TargetKeyArn pulumi.StringOutput `pulumi:"targetKeyArn"`

    TargetKeyId pulumi.StringOutput `pulumi:"targetKeyId"`
}

Usage Example

key, _ := kms.NewKey(ctx, "myKey", nil)

alias, _ := kms.NewAlias(ctx, "myKeyAlias", &kms.AliasArgs{
    Name:        pulumi.String("alias/my-app-key"),
    TargetKeyId: key.KeyId,
})
// Reference key by alias: alias.Name or alias.Arn

Resource: Grant

Provides fine-grained, resource-based access control for KMS keys. Useful for cross-account access or delegating KMS key usage.

func NewGrant(ctx *pulumi.Context,
    name string, args *GrantArgs, opts ...pulumi.ResourceOption) (*Grant, error)

func GetGrant(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *GrantState, opts ...pulumi.ResourceOption) (*Grant, error)

GrantArgs

type GrantArgs struct {
    // Encryption context conditions for the grant.
    Constraints GrantConstraintArrayInput

    // List of grant tokens for creating the grant.
    GrantCreationTokens pulumi.StringArrayInput

    // ARN of the principal receiving permission.
    GranteePrincipal pulumi.StringInput

    // Key ID or ARN of the KMS key.
    KeyId pulumi.StringInput

    // Friendly name for the grant.
    Name pulumi.StringPtrInput

    // List of operations the grant permits.
    // Valid: Decrypt, Encrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext,
    //   ReEncryptFrom, ReEncryptTo, Sign, Verify, GetPublicKey,
    //   CreateGrant, RetireGrant, DescribeKey, GenerateDataKeyPair,
    //   GenerateDataKeyPairWithoutPlaintext.
    Operations pulumi.StringArrayInput

    // AWS region for this resource.
    Region pulumi.StringPtrInput

    // If false (default), grant is revoked on delete.
    // If true, grant is retired on delete (requires special permissions).
    RetireOnDelete pulumi.BoolPtrInput

    // ARN of principal that can retire the grant.
    RetiringPrincipal pulumi.StringPtrInput
}

Grant (Output Fields)

type Grant struct {
    pulumi.CustomResourceState

    Constraints         GrantConstraintArrayOutput `pulumi:"constraints"`
    GrantCreationTokens pulumi.StringArrayOutput   `pulumi:"grantCreationTokens"`

    // Unique identifier for the grant.
    GrantId pulumi.StringOutput `pulumi:"grantId"`

    // Grant token for the created grant.
    GrantToken      pulumi.StringOutput    `pulumi:"grantToken"`
    GranteePrincipal pulumi.StringOutput   `pulumi:"granteePrincipal"`
    KeyId           pulumi.StringOutput    `pulumi:"keyId"`
    Name            pulumi.StringOutput    `pulumi:"name"`
    Operations      pulumi.StringArrayOutput `pulumi:"operations"`
    Region          pulumi.StringOutput    `pulumi:"region"`
    RetireOnDelete  pulumi.BoolPtrOutput   `pulumi:"retireOnDelete"`
    RetiringPrincipal pulumi.StringPtrOutput `pulumi:"retiringPrincipal"`
}

Resource: KeyPolicy

Standalone resource to manage the key policy for a KMS key. Do not use together with the Policy argument of kms.Key.

func NewKeyPolicy(ctx *pulumi.Context,
    name string, args *KeyPolicyArgs, opts ...pulumi.ResourceOption) (*KeyPolicy, error)

func GetKeyPolicy(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *KeyPolicyState, opts ...pulumi.ResourceOption) (*KeyPolicy, error)

KeyPolicyArgs

type KeyPolicyArgs struct {
    // Flag to bypass the key policy lockout safety check.
    BypassPolicyLockoutSafetyCheck pulumi.BoolPtrInput

    // ID of the KMS key.
    KeyId pulumi.StringInput

    // Valid JSON policy document.
    Policy pulumi.StringInput

    // AWS region for this resource.
    Region pulumi.StringPtrInput
}

Data Source: LookupKey

Retrieves detailed information about a KMS key using its ID, ARN, or alias.

func LookupKey(ctx *pulumi.Context, args *LookupKeyArgs, opts ...pulumi.InvokeOption) (*LookupKeyResult, error)

LookupKeyArgs

type LookupKeyArgs struct {
    // List of grant tokens.
    GrantTokens []string `pulumi:"grantTokens"`

    // Key identifier in one of the following formats:
    //   - Key ID:     "1234abcd-12ab-34cd-56ef-1234567890ab"
    //   - Key ARN:    "arn:aws:kms:us-east-1:111122223333:key/1234abcd-..."
    //   - Alias name: "alias/my-key"
    //   - Alias ARN:  "arn:aws:kms:us-east-1:111122223333:alias/my-key"
    KeyId string `pulumi:"keyId"`

    // AWS region.
    Region *string `pulumi:"region"`
}

LookupKeyResult

type LookupKeyResult struct {
    // ARN of the key.
    Arn string `pulumi:"arn"`

    // AWS account ID owning the key.
    AwsAccountId string `pulumi:"awsAccountId"`

    CloudHsmClusterId string `pulumi:"cloudHsmClusterId"`
    CreationDate      string `pulumi:"creationDate"`
    CustomKeyStoreId  string `pulumi:"customKeyStoreId"`

    // See KeySpec.
    CustomerMasterKeySpec string `pulumi:"customerMasterKeySpec"`

    // Deletion date (only present when KeyState is PendingDeletion).
    DeletionDate string `pulumi:"deletionDate"`
    Description  string `pulumi:"description"`

    // True when KeyState is Enabled.
    Enabled         bool     `pulumi:"enabled"`
    ExpirationModel string   `pulumi:"expirationModel"`
    GrantTokens     []string `pulumi:"grantTokens"`
    Id              string   `pulumi:"id"`
    KeyId           string   `pulumi:"keyId"`
    KeyManager      string   `pulumi:"keyManager"`

    // Type of key material: SYMMETRIC_DEFAULT, RSA_*, ECC_*, HMAC_*, etc.
    KeySpec string `pulumi:"keySpec"`

    // State: Enabled, Disabled, PendingDeletion, PendingImport, Unavailable.
    KeyState string `pulumi:"keyState"`

    // Intended use: ENCRYPT_DECRYPT, SIGN_VERIFY, GENERATE_VERIFY_MAC.
    KeyUsage string `pulumi:"keyUsage"`

    // True for multi-Region keys.
    MultiRegion bool `pulumi:"multiRegion"`

    // Multi-region configuration (only for multi-region keys).
    MultiRegionConfigurations []GetKeyMultiRegionConfiguration `pulumi:"multiRegionConfigurations"`

    // AWS_KMS (AWS-created material) or EXTERNAL (imported material).
    Origin string `pulumi:"origin"`

    PendingDeletionWindowInDays int    `pulumi:"pendingDeletionWindowInDays"`
    Region                      string `pulumi:"region"`
    ValidTo                     string `pulumi:"validTo"`
    XksKeyConfigurations        []GetKeyXksKeyConfiguration `pulumi:"xksKeyConfigurations"`
}

Usage Example

// Look up a key by alias to get its ARN
keyData, err := kms.LookupKey(ctx, &kms.LookupKeyArgs{
    KeyId: "alias/my-app-key",
}, nil)
if err != nil {
    return err
}
// keyData.Arn contains the full ARN
// keyData.KeyId contains the key ID

Common KMS Patterns

Pattern 1: Key with Alias for Service Encryption

import (
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/kms"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

key, err := kms.NewKey(ctx, "appKey", &kms.KeyArgs{
    Description:          pulumi.String("Application data encryption key"),
    EnableKeyRotation:    pulumi.Bool(true),
    DeletionWindowInDays: pulumi.Int(7),
    Tags: pulumi.StringMap{
        "App": pulumi.String("my-app"),
    },
})

alias, err := kms.NewAlias(ctx, "appKeyAlias", &kms.AliasArgs{
    Name:        pulumi.String("alias/my-app-key"),
    TargetKeyId: key.KeyId,
})
// Use key.Arn or alias.TargetKeyArn when configuring KmsKeyId in other resources

Pattern 2: Key with IAM Policy via GetPolicyDocument

import (
    "fmt"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/iam"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/kms"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

current, _ := aws.GetCallerIdentity(ctx, nil, nil)

keyPolicy, _ := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Sid:    pulumi.StringRef("EnableIAMUserPermissions"),
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type:        "AWS",
                    Identifiers: []string{fmt.Sprintf("arn:aws:iam::%s:root", current.AccountId)},
                },
            },
            Actions:   []string{"kms:*"},
            Resources: []string{"*"},
        },
        {
            Sid:    pulumi.StringRef("AllowKeyAdministration"),
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type:        "AWS",
                    Identifiers: []string{fmt.Sprintf("arn:aws:iam::%s:role/AdminRole", current.AccountId)},
                },
            },
            Actions: []string{
                "kms:Create*", "kms:Describe*", "kms:Enable*",
                "kms:List*", "kms:Put*", "kms:Update*",
                "kms:Revoke*", "kms:Disable*", "kms:Get*",
                "kms:Delete*", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion",
            },
            Resources: []string{"*"},
        },
        {
            Sid:    pulumi.StringRef("AllowKeyUse"),
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type:        "AWS",
                    Identifiers: []string{fmt.Sprintf("arn:aws:iam::%s:role/AppRole", current.AccountId)},
                },
            },
            Actions: []string{
                "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*",
                "kms:GenerateDataKey", "kms:DescribeKey",
            },
            Resources: []string{"*"},
        },
    },
}, nil)

key, _ := kms.NewKey(ctx, "appKey", &kms.KeyArgs{
    Description:          pulumi.String("App encryption key with explicit policy"),
    EnableKeyRotation:    pulumi.Bool(true),
    DeletionWindowInDays: pulumi.Int(7),
    Policy:               pulumi.String(keyPolicy.Json),
})

KMS Import

# Key
pulumi import aws:kms/key:Key example 1234abcd-12ab-34cd-56ef-1234567890ab

# Alias
pulumi import aws:kms/alias:Alias example alias/my-key-alias

# Grant
pulumi import aws:kms/grant:Grant example 1234abcd-12ab-34cd-56ef-1234567890ab:abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514

Secrets Manager Package

Package import path: github.com/pulumi/pulumi-aws/sdk/v7/go/aws/secretsmanager

import "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/secretsmanager"

Overview

The Secrets Manager package manages AWS Secrets Manager resources for securely storing, retrieving, and rotating secrets (API keys, database credentials, etc.). KMS integration is supported for encryption at rest.

Resource and Data Source Index

Resources (New*)

  • NewSecret - Creates a secret container (metadata only)
  • NewSecretVersion - Creates/manages the secret value
  • NewSecretPolicy - Attaches a resource-based policy to a secret
  • NewSecretRotation - Configures automatic secret rotation
  • NewTag - Standalone tag management for a secret

Data Sources (Get*/Lookup*)

  • LookupSecret - Look up secret metadata by ARN or name
  • LookupSecretVersion - Retrieve a secret version and its value
  • GetRandomPassword - Generate a random password
  • GetSecretPolicy - Get the resource policy of a secret
  • GetSecretRotation - Get rotation configuration of a secret
  • GetSecretVersions - List versions of a secret
  • GetSecrets - List secrets

Resource: Secret

Manages AWS Secrets Manager secret metadata. To store a value, use SecretVersion. To configure rotation, use SecretRotation.

func NewSecret(ctx *pulumi.Context,
    name string, args *SecretArgs, opts ...pulumi.ResourceOption) (*Secret, error)

func GetSecret(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *SecretState, opts ...pulumi.ResourceOption) (*Secret, error)

SecretArgs

type SecretArgs struct {
    // Description of the secret.
    Description pulumi.StringPtrInput

    // Whether to overwrite the secret in a destination Region during replication.
    ForceOverwriteReplicaSecret pulumi.BoolPtrInput

    // ARN or ID of a KMS key for encrypting secret values.
    // Defaults to the AWS account default KMS key (aws/secretsmanager).
    KmsKeyId pulumi.StringPtrInput

    // Friendly name. Allowed chars: A-Z a-z 0-9 /_+=.@-
    // Conflicts with NamePrefix.
    Name pulumi.StringPtrInput

    // Unique name prefix. Conflicts with Name.
    NamePrefix pulumi.StringPtrInput

    // Resource-based policy document (JSON). Set to "{}" to delete an existing policy.
    // NOTE: Setting to null/empty does NOT delete the policy - use SecretPolicy resource.
    Policy pulumi.StringPtrInput

    // Days before deletion (0 for immediate, 7-30 for recovery window). Defaults to 30.
    RecoveryWindowInDays pulumi.IntPtrInput

    // AWS region for this resource.
    Region pulumi.StringPtrInput

    // Configuration blocks for cross-region replication.
    Replicas SecretReplicaArrayInput

    // Key-value map of tags.
    Tags pulumi.StringMapInput
}

Secret (Output Fields)

type Secret struct {
    pulumi.CustomResourceState

    // ARN of the secret.
    Arn pulumi.StringOutput `pulumi:"arn"`

    Description                 pulumi.StringPtrOutput   `pulumi:"description"`
    ForceOverwriteReplicaSecret pulumi.BoolPtrOutput     `pulumi:"forceOverwriteReplicaSecret"`
    KmsKeyId                    pulumi.StringPtrOutput   `pulumi:"kmsKeyId"`
    Name                        pulumi.StringOutput      `pulumi:"name"`
    NamePrefix                  pulumi.StringOutput      `pulumi:"namePrefix"`
    Policy                      pulumi.StringOutput      `pulumi:"policy"`
    RecoveryWindowInDays        pulumi.IntPtrOutput      `pulumi:"recoveryWindowInDays"`
    Region                      pulumi.StringOutput      `pulumi:"region"`
    Replicas                    SecretReplicaArrayOutput `pulumi:"replicas"`
    Tags                        pulumi.StringMapOutput   `pulumi:"tags"`
    TagsAll                     pulumi.StringMapOutput   `pulumi:"tagsAll"`
}

Usage Example

secret, err := secretsmanager.NewSecret(ctx, "dbPassword", &secretsmanager.SecretArgs{
    Name:        pulumi.String("prod/db/password"),
    Description: pulumi.String("Production database password"),
    KmsKeyId:    kmsKey.Arn,
    RecoveryWindowInDays: pulumi.Int(7),
    Tags: pulumi.StringMap{
        "Environment": pulumi.String("prod"),
    },
})

Resource: SecretVersion

Manages the actual secret value stored in a secret. Creates a new version of the secret.

func NewSecretVersion(ctx *pulumi.Context,
    name string, args *SecretVersionArgs, opts ...pulumi.ResourceOption) (*SecretVersion, error)

func GetSecretVersion(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *SecretVersionState, opts ...pulumi.ResourceOption) (*SecretVersion, error)

SecretVersionArgs

type SecretVersionArgs struct {
    // AWS region for this resource.
    Region pulumi.StringPtrInput

    // Binary data to encrypt and store (base64 encoded).
    // Required if SecretString and SecretStringWo are not set.
    SecretBinary pulumi.StringPtrInput

    // ARN or name of the secret.
    SecretId pulumi.StringInput

    // Text data to encrypt and store.
    // Required if SecretBinary and SecretStringWo are not set.
    SecretString pulumi.StringPtrInput

    // Write-only text data (does not appear in state reads).
    // Required if SecretBinary and SecretString are not set.
    SecretStringWo pulumi.StringPtrInput

    // Increment to trigger updates when SecretStringWo changes.
    SecretStringWoVersion pulumi.IntPtrInput

    // List of staging labels. Include "AWSCURRENT" if this is the current version.
    VersionStages pulumi.StringArrayInput
}

SecretVersion (Output Fields)

type SecretVersion struct {
    pulumi.CustomResourceState

    // ARN of the secret.
    Arn               pulumi.StringOutput      `pulumi:"arn"`
    HasSecretStringWo pulumi.BoolOutput        `pulumi:"hasSecretStringWo"`
    Region            pulumi.StringOutput      `pulumi:"region"`
    SecretBinary      pulumi.StringPtrOutput   `pulumi:"secretBinary"`
    SecretId          pulumi.StringOutput      `pulumi:"secretId"`
    SecretString      pulumi.StringPtrOutput   `pulumi:"secretString"`
    SecretStringWo    pulumi.StringPtrOutput   `pulumi:"secretStringWo"`
    SecretStringWoVersion pulumi.IntPtrOutput  `pulumi:"secretStringWoVersion"`

    // Unique identifier of this version.
    VersionId     pulumi.StringOutput      `pulumi:"versionId"`
    VersionStages pulumi.StringArrayOutput `pulumi:"versionStages"`
}

Usage Examples

Simple string secret:

version, err := secretsmanager.NewSecretVersion(ctx, "dbPasswordValue", &secretsmanager.SecretVersionArgs{
    SecretId:     secret.ID(),
    SecretString: pulumi.String("my-super-secret-password"),
})

JSON key-value secret:

import (
    "encoding/json"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/secretsmanager"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

credentials, _ := json.Marshal(map[string]string{
    "username": "dbadmin",
    "password": "my-secret-password",
    "host":     "db.example.com",
    "port":     "5432",
})

version, err := secretsmanager.NewSecretVersion(ctx, "dbCredentials", &secretsmanager.SecretVersionArgs{
    SecretId:     secret.ID(),
    SecretString: pulumi.String(string(credentials)),
})

Resource: SecretPolicy

Attaches a resource-based policy to a secret for cross-account access control.

func NewSecretPolicy(ctx *pulumi.Context,
    name string, args *SecretPolicyArgs, opts ...pulumi.ResourceOption) (*SecretPolicy, error)

func GetSecretPolicy(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *SecretPolicyState, opts ...pulumi.ResourceOption) (*SecretPolicy, error)

SecretPolicyArgs

type SecretPolicyArgs struct {
    // Whether to validate the policy to prevent broad access.
    BlockPublicPolicy pulumi.BoolPtrInput

    // Valid JSON policy document. "{}" is not valid - must be a real policy.
    Policy pulumi.StringInput

    // AWS region for this resource.
    Region pulumi.StringPtrInput

    // ARN of the secret.
    SecretArn pulumi.StringInput
}

SecretPolicy (Output Fields)

type SecretPolicy struct {
    pulumi.CustomResourceState

    BlockPublicPolicy pulumi.BoolPtrOutput `pulumi:"blockPublicPolicy"`
    Policy            pulumi.StringOutput  `pulumi:"policy"`
    Region            pulumi.StringOutput  `pulumi:"region"`
    SecretArn         pulumi.StringOutput  `pulumi:"secretArn"`
}

Usage Example (Cross-account access)

crossAccountPolicy, _ := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Sid:    pulumi.StringRef("AllowCrossAccountAccess"),
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type:        "AWS",
                    Identifiers: []string{"arn:aws:iam::987654321098:root"},
                },
            },
            Actions:   []string{"secretsmanager:GetSecretValue"},
            Resources: []string{"*"},
        },
    },
}, nil)

_, err := secretsmanager.NewSecretPolicy(ctx, "crossAccountPolicy", &secretsmanager.SecretPolicyArgs{
    SecretArn:         secret.Arn,
    Policy:            pulumi.String(crossAccountPolicy.Json),
    BlockPublicPolicy: pulumi.Bool(true),
})

Resource: SecretRotation

Configures automatic rotation for a secret using a Lambda function.

func NewSecretRotation(ctx *pulumi.Context,
    name string, args *SecretRotationArgs, opts ...pulumi.ResourceOption) (*SecretRotation, error)

func GetSecretRotation(ctx *pulumi.Context,
    name string, id pulumi.IDInput, state *SecretRotationState, opts ...pulumi.ResourceOption) (*SecretRotation, error)

SecretRotationArgs

type SecretRotationArgs struct {
    // AWS region for this resource.
    Region pulumi.StringPtrInput

    // Whether to rotate immediately when rotation is enabled. Defaults to true.
    RotateImmediately pulumi.BoolPtrInput

    // ARN of the Lambda function that rotates the secret.
    // Required for non-AWS-managed secrets.
    RotationLambdaArn pulumi.StringPtrInput

    // Rotation schedule configuration.
    RotationRules SecretRotationRotationRulesInput

    // ARN or name of the secret to rotate.
    SecretId pulumi.StringInput
}

SecretRotation (Output Fields)

type SecretRotation struct {
    pulumi.CustomResourceState

    Region pulumi.StringOutput `pulumi:"region"`

    // Whether to rotate immediately.
    RotateImmediately pulumi.BoolPtrOutput `pulumi:"rotateImmediately"`

    // Whether automatic rotation is enabled.
    RotationEnabled   pulumi.BoolOutput   `pulumi:"rotationEnabled"`
    RotationLambdaArn pulumi.StringPtrOutput `pulumi:"rotationLambdaArn"`
    RotationRules     SecretRotationRotationRulesOutput `pulumi:"rotationRules"`
    SecretId          pulumi.StringOutput `pulumi:"secretId"`
}

SecretRotationRotationRulesArgs

type SecretRotationRotationRulesArgs struct {
    // Rotation interval in days (if using days-based schedule).
    AutomaticallyAfterDays pulumi.IntPtrInput

    // Duration in hours for the rotation window.
    Duration pulumi.StringPtrInput

    // Cron or rate expression for rotation schedule.
    // Example: "cron(0 16 1,15 * ? *)" or "rate(10 days)"
    ScheduleExpression pulumi.StringPtrInput
}

Usage Example

_, err := secretsmanager.NewSecretRotation(ctx, "rotation", &secretsmanager.SecretRotationArgs{
    SecretId:          secret.ID(),
    RotationLambdaArn: rotationLambda.Arn,
    RotationRules: &secretsmanager.SecretRotationRotationRulesArgs{
        AutomaticallyAfterDays: pulumi.Int(30),
    },
})

Data Source: LookupSecret

Retrieves metadata about an existing Secrets Manager secret.

func LookupSecret(ctx *pulumi.Context, args *LookupSecretArgs, opts ...pulumi.InvokeOption) (*LookupSecretResult, error)

LookupSecretArgs

type LookupSecretArgs struct {
    // ARN of the secret to retrieve.
    Arn *string `pulumi:"arn"`

    // Name of the secret to retrieve.
    Name *string `pulumi:"name"`

    // AWS region.
    Region *string `pulumi:"region"`

    // Tags of the secret.
    Tags map[string]string `pulumi:"tags"`
}

LookupSecretResult

type LookupSecretResult struct {
    // ARN of the secret.
    Arn string `pulumi:"arn"`

    // Created date in UTC.
    CreatedDate string `pulumi:"createdDate"`

    Description string `pulumi:"description"`
    Id          string `pulumi:"id"`

    // KMS Customer Master Key associated with the secret.
    KmsKeyId string `pulumi:"kmsKeyId"`

    LastChangedDate string            `pulumi:"lastChangedDate"`
    Name            string            `pulumi:"name"`

    // Resource-based policy document attached to the secret.
    Policy string            `pulumi:"policy"`
    Region string            `pulumi:"region"`
    Tags   map[string]string `pulumi:"tags"`
}

Usage Example

// Look up an existing secret by name
secretData, err := secretsmanager.LookupSecret(ctx, &secretsmanager.LookupSecretArgs{
    Name: pulumi.StringRef("prod/db/password"),
}, nil)
if err != nil {
    return err
}
// secretData.Arn - use this ARN to reference the secret
// secretData.KmsKeyId - the KMS key encrypting this secret

Data Source: LookupSecretVersion

Retrieves a specific version of a secret including the secret value.

func LookupSecretVersion(ctx *pulumi.Context, args *LookupSecretVersionArgs, opts ...pulumi.InvokeOption) (*LookupSecretVersionResult, error)

LookupSecretVersionArgs

type LookupSecretVersionArgs struct {
    // AWS region.
    Region *string `pulumi:"region"`

    // ARN or name of the secret.
    SecretId string `pulumi:"secretId"`

    // Unique identifier of the version. Overrides VersionStage.
    VersionId *string `pulumi:"versionId"`

    // Staging label of the version to retrieve. Defaults to "AWSCURRENT".
    VersionStage *string `pulumi:"versionStage"`
}

LookupSecretVersionResult

type LookupSecretVersionResult struct {
    // ARN of the secret.
    Arn string `pulumi:"arn"`

    CreatedDate string `pulumi:"createdDate"`
    Id          string `pulumi:"id"`
    Region      string `pulumi:"region"`

    // Decrypted binary data (base64 encoded).
    SecretBinary string `pulumi:"secretBinary"`
    SecretId     string `pulumi:"secretId"`

    // Decrypted text data.
    SecretString string `pulumi:"secretString"`

    // Unique identifier of this version.
    VersionId     string   `pulumi:"versionId"`
    VersionStage  *string  `pulumi:"versionStage"`
    VersionStages []string `pulumi:"versionStages"`
}

Usage Examples

Retrieve current secret value:

// Retrieve AWSCURRENT version (default)
secretVersion, err := secretsmanager.LookupSecretVersion(ctx, &secretsmanager.LookupSecretVersionArgs{
    SecretId: "prod/db/password",
}, nil)
// secretVersion.SecretString contains the decrypted value

Retrieve specific version:

secretVersion, err := secretsmanager.LookupSecretVersion(ctx, &secretsmanager.LookupSecretVersionArgs{
    SecretId:     "prod/db/password",
    VersionStage: pulumi.StringRef("AWSPREVIOUS"),
}, nil)

Common Secrets Manager Patterns

Pattern 1: Complete Secret with KMS Encryption

import (
    "encoding/json"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/kms"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/secretsmanager"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

// 1. Create KMS key for encryption
kmsKey, _ := kms.NewKey(ctx, "secretsKey", &kms.KeyArgs{
    Description:          pulumi.String("Key for secrets encryption"),
    EnableKeyRotation:    pulumi.Bool(true),
    DeletionWindowInDays: pulumi.Int(7),
})

kmsAlias, _ := kms.NewAlias(ctx, "secretsKeyAlias", &kms.AliasArgs{
    Name:        pulumi.String("alias/my-app-secrets"),
    TargetKeyId: kmsKey.KeyId,
})

// 2. Create secret container
secret, _ := secretsmanager.NewSecret(ctx, "dbCredentials", &secretsmanager.SecretArgs{
    Name:                 pulumi.String("prod/myapp/db-credentials"),
    Description:          pulumi.String("Database credentials for prod"),
    KmsKeyId:             kmsKey.Arn,
    RecoveryWindowInDays: pulumi.Int(7),
})

// 3. Store the secret value
creds, _ := json.Marshal(map[string]string{
    "username": "admin",
    "password": "initial-placeholder",
})

secretVersion, _ := secretsmanager.NewSecretVersion(ctx, "dbCredsVersion", &secretsmanager.SecretVersionArgs{
    SecretId:     secret.ID(),
    SecretString: pulumi.String(string(creds)),
})

Pattern 2: Secret with Cross-Account Policy

import (
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/iam"
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/secretsmanager"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

secret, _ := secretsmanager.NewSecret(ctx, "sharedSecret", &secretsmanager.SecretArgs{
    Name: pulumi.String("shared/api-key"),
})

policy, _ := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Sid:    pulumi.StringRef("AllowConsumerAccount"),
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {Type: "AWS", Identifiers: []string{"arn:aws:iam::111122223333:root"}},
            },
            Actions:   []string{"secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"},
            Resources: []string{"*"},
        },
    },
}, nil)

_, _ = secretsmanager.NewSecretPolicy(ctx, "sharedSecretPolicy", &secretsmanager.SecretPolicyArgs{
    SecretArn: secret.Arn,
    Policy:    pulumi.String(policy.Json),
})

Pattern 3: Referencing Secrets in IAM Policies

// Allow a Lambda function to access a specific secret
lambdaPolicy, _ := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Effect:    pulumi.StringRef("Allow"),
            Actions:   []string{"secretsmanager:GetSecretValue"},
            Resources: pulumi.StringArrayOutput{secret.Arn}.ToStringArrayOutput(),
        },
        {
            Effect:    pulumi.StringRef("Allow"),
            Actions:   []string{"kms:Decrypt"},
            Resources: pulumi.StringArrayOutput{kmsKey.Arn}.ToStringArrayOutput(),
        },
    },
}, nil)

Secrets Manager Import

# Secret
pulumi import aws:secretsmanager/secret:Secret example arn:aws:secretsmanager:us-east-1:123456789012:secret:example-123456

# SecretVersion
pulumi import aws:secretsmanager/secretVersion:SecretVersion example 'arn:aws:secretsmanager:us-east-1:123456789012:secret:example-123456|xxxxx-xxxxxxx-xxxxxxx-xxxxx'

# SecretPolicy
pulumi import aws:secretsmanager/secretPolicy:SecretPolicy example arn:aws:secretsmanager:us-east-1:123456789012:secret:example-123456

# SecretRotation
pulumi import aws:secretsmanager/secretRotation:SecretRotation example arn:aws:secretsmanager:us-east-1:123456789012:secret:example-123456

Install with Tessl CLI

npx tessl i tessl/golang-github-com-pulumi-pulumi-aws-sdk-v7

docs

reference

iam-security

iam.md

kms.md

core-data-sources.md

provider.md

index.md

tile.json