本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從 取得秘密 AWS Secrets Manager 擷取機密時，Secrets Manager 會產生 CloudTrail 日誌項目。如需詳細資訊，請參閱[使用 記錄 AWS Secrets Manager 事件 AWS CloudTrail](monitoring-cloudtrail.md)。 **Topics** + [Java](retrieving-secrets-java.md) + [Python](retrieving-secrets-python.md) + [.NET](retrieving-secrets-net.md) + [Go](retrieving-secrets-go.md) + [Rust](retrieving-secrets-rust.md) + [Amazon EKS](integrate_eks.md) + [AWS Lambda](retrieving-secrets_lambda.md) + [Secrets Manager 代理程式](secrets-manager-agent.md) + [C\$1\$1](retrieving-secrets-cpp.md) + [JavaScript](retrieving-secrets-javascript.md) + [Kotlin](retrieving-secrets-kotlin.md) + [PHP](retrieving-secrets-php.md) + [Ruby](retrieving-secrets-ruby.md) + [AWS CLI](retrieving-secrets_cli.md) + [AWS 主控台](retrieving-secrets-console.md) + [AWS Batch](integrating_BATCH.md) + [CloudFormation](cfn-example_reference-secret.md) + [GitHub 工作](retrieving-secrets_github.md) + [GitLab](integrating_gitlab.md) + [AWS IoT Greengrass](integrating-greengrass.md) + [參數存放區](integrating_parameterstore.md) # 使用 Java 取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 若要使用秘密中的登入資料連線到資料庫，您可以使用 Secrets Manager SQL Connection 驅動程式，以包裝基本 JDBC 驅動程式。這也使用用戶端快取，因此可以降低呼叫 Secrets Manager APIs的成本。 **Topics** + [使用 Java 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-java.md) + [使用 JDBC 搭配 AWS Secrets Manager 秘密中的登入資料連線至 SQL 資料庫](retrieving-secrets_jdbc.md) + [使用 Java AWS 開發套件取得 Secrets Manager 秘密值](retrieving-secrets-java-sdk.md) # 使用 Java 搭配用戶端快取取得 Secrets Manager 秘密值 擷取秘密時，您可以使用 Secrets Manager Java 型快取元件進行快取以供將來使用。擷取快取的秘密比從 Secrets Manager 中擷取要快。由於呼叫 Secrets Manager API 需要花費成本，因此使用快取可以降低成本。如需您可以擷取機密的所有方法，請參閱 [取得秘密](retrieving-secrets.md)。 快取政策是「最近最少使用的 (LRU)」，因此當快取必須丟棄秘密時，其會丟棄最近最少使用的秘密。預設情況下，快取每小時重新整理一次秘密。您可以設定在快取中[重新整理機密的頻率](retrieving-secrets_cache-java-ref_SecretCacheConfiguration.md#retrieving-secrets_cache-java-ref_SecretCacheConfiguration_methods-getCacheItemTTL)，並可以[掛接到機密擷取](retrieving-secrets_cache-java-ref_SecretCacheHook.md)以新增更多功能。 一旦釋放快取參考，快取不會強制執行垃圾回收。快取實作不包括快取失效。快取實作著重於快取本身，而不是強化或著重於安全性。如果您需要額外的安全性，例如加密快取中的項目，請使用提供的介面和抽象方法。 若要使用元件，您必須擁有下列項目： + Java 8 或更高版本的開發環境。請參閱 Oracle 網站上的 [Java SE 下載](https://www.oracle.com/technetwork/java/javase/downloads/index.html)。 若要下載開放程式碼，請參閱 [Secrets Manager Java 型快取用戶端元件](https://github.com/aws/aws-secretsmanager-caching-java) (在 GitHub 上)。 要將元件新增至您的專案中，請在 Maven pom.xml 檔案中包含以下相依性。如需 Maven 的詳細資訊，請參閱 Apache Maven 專案網站上的[入門指南](https://maven.apache.org/guides/getting-started/index.html)。 ``` com.amazonaws.secretsmanager aws-secretsmanager-caching-java 1.0.2 ``` **必要許可：** + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需詳細資訊，請參閱[許可參考](auth-and-access.md#reference_iam-permissions)。 **Topics** + [SecretCache](retrieving-secrets_cache-java-ref_SecretCache.md) + [SecretCacheConfiguration](retrieving-secrets_cache-java-ref_SecretCacheConfiguration.md) + [SecretCacheHook](retrieving-secrets_cache-java-ref_SecretCacheHook.md) **Example 擷取秘密** 下列程式碼範例顯示擷取秘密字串的 Lambda 函數。它遵循將函數處理常式之外的快取執行個體化的[最佳實務](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)，所以如果您再次呼叫 Lambda 函數，則不會繼續呼叫 API。 ``` package com.amazonaws.secretsmanager.caching.examples; import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; import com.amazonaws.services.lambda.runtime.LambdaLogger; import com.amazonaws.secretsmanager.caching.SecretCache; public class SampleClass implements RequestHandler { private final SecretCache cache = new SecretCache(); @Override public String handleRequest(String secretId, Context context) { final String secret = cache.getSecretString(secretId); // Use the secret, return success; } } ``` # SecretCache 從 Secrets Manager 請求的秘密記憶體內快取。您使用 [getSecretString](#retrieving-secrets_cache-java-ref_SecretCache-methods-getSecretString) 或 [getSecretBinary](#retrieving-secrets_cache-java-ref_SecretCache-methods-getSecretBinary) 從快取中擷取秘密。您可以透過在建構函式的 [SecretCacheConfiguration](retrieving-secrets_cache-java-ref_SecretCacheConfiguration.md) 物件中傳遞，設定快取設定。 如需包含範例的詳細資訊，請參閱 [使用 Java 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-java.md)。 ## 建構函式 `public SecretCache()` `SecretCache` 物件的預設建構函式。 `public SecretCache(AWSSecretsManagerClientBuilder builder)` 使用以提供的 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClientBuilder.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClientBuilder.html) 建立的 Secrets Manager 用戶端建構新快取。使用此建構函數自訂 Secrets Manager 用戶端，例如使用特定區域或端點。 `public SecretCache(AWSSecretsManager client)` 使用提供的 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html) 建構新的秘密快取。使用此建構函數自訂 Secrets Manager 用戶端，例如使用特定區域或端點。 `public SecretCache(SecretCacheConfiguration config)` 使用提供的 `SecretCacheConfiguration` 建構新的秘密快取。 ## 方法 ### getSecretString `public String getSecretString(final String secretId)` 從 Secrets Manager 中擷取字串秘密。傳回 [https://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true](https://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true)。 ### getSecretBinary `public ByteBuffer getSecretBinary(final String secretId)` 從 Secrets Manager 中擷取二進位秘密。傳回 [https://docs.oracle.com/javase/7/docs/api/java/nio/ByteBuffer.html](https://docs.oracle.com/javase/7/docs/api/java/nio/ByteBuffer.html)。 ### refreshNow `public boolean refreshNow(final String secretId) throws InterruptedException` 強制重新整理快取。如果重新整理完成且沒有錯誤，則會傳回 `true`，否則會傳回 `false`。 ### 關閉 `public void close()` 關閉快取。 # SecretCacheConfiguration [SecretCache](retrieving-secrets_cache-java-ref_SecretCache.md) 的快取組態選項，例如最大快取大小和快取秘密的存留時間 (TTL)。 ## 建構函數 `public SecretCacheConfiguration` `SecretCacheConfiguration` 物件的預設建構函式。 ## 方法 ### getClient `public AWSSecretsManager getClient()` 傳回 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html)，快取從中擷取秘密。 ### setClient `public void setClient(AWSSecretsManager client)` 傳回 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html) 用戶端，快取從中擷取秘密。 ### getCacheHook `public SecretCacheHook getCacheHook()` 傳回用於與快取更新掛鉤的 [SecretCacheHook](retrieving-secrets_cache-java-ref_SecretCacheHook.md) 介面。 ### setCacheHook `public void setCacheHook(SecretCacheHook cacheHook)` 設定用於與快取更新掛鉤的 [SecretCacheHook](retrieving-secrets_cache-java-ref_SecretCacheHook.md) 介面。 ### getMaxCacheSize `public int getMaxCacheSize()` 傳回最大快取大小。預設值為 1024 個秘密。 ### setMaxCacheSize `public void setMaxCacheSize(int maxCacheSize)` 設定最大快取大小。預設值為 1024 個秘密。 ### getCacheItemTTL `public long getCacheItemTTL()` 傳回快取項目的 TTL (以毫秒為單位)。當快取的秘密超過此 TTL 時，快取會從 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html) 擷取秘密的新複本。預設值為 1 小時 (以毫秒為單位)。 當在 TTL 之後請求秘密時，快取會同步重新整理秘密。如果同步重新整理失敗，則快取會傳回過時的秘密。 ### setCacheItemTTL `public void setCacheItemTTL(long cacheItemTTL)` 設定快取項目的 TTL (以毫秒為單位)。當快取的秘密超過此 TTL 時，快取會從 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html) 擷取秘密的新複本。預設值為 1 小時 (以毫秒為單位)。 ### getVersionStage `public String getVersionStage()` 傳回要快取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。預設為 ` "AWSCURRENT"`。 ### setVersionStage `public void setVersionStage(String versionStage)` 設定要快取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。預設為 `"AWSCURRENT"`。 ### SecretCacheConfiguration withClient `public SecretCacheConfiguration withClient(AWSSecretsManager client)` 設定 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html)，以從中擷取秘密。使用新設定傳回已更新的 `SecretCacheConfiguration` 物件。 ### SecretCacheConfiguration withCacheHook `public SecretCacheConfiguration withCacheHook(SecretCacheHook cacheHook)` 設定用於與記憶體內快取掛鉤的介面。使用新設定傳回已更新的 `SecretCacheConfiguration` 物件。 ### SecretCacheConfiguration withMaxCacheSize `public SecretCacheConfiguration withMaxCacheSize(int maxCacheSize)` 設定最大快取大小。使用新設定傳回已更新的 `SecretCacheConfiguration` 物件。 ### SecretCacheConfiguration withCacheItemTTL `public SecretCacheConfiguration withCacheItemTTL(long cacheItemTTL)` 設定快取項目的 TTL (以毫秒為單位)。當快取的秘密超過此 TTL 時，快取會從 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/AWSSecretsManagerClient.html) 擷取秘密的新複本。預設值為 1 小時 (以毫秒為單位)。使用新設定傳回已更新的 `SecretCacheConfiguration` 物件。 ### SecretCacheConfiguration withVersionStage `public SecretCacheConfiguration withVersionStage(String versionStage)` 設定要快取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。使用新設定傳回已更新的 `SecretCacheConfiguration` 物件。 # SecretCacheHook 用於掛接到 [SecretCache](retrieving-secrets_cache-java-ref_SecretCache.md)，以對存放在快取中的秘密執行動作的介面。 ## put `Object put(final Object o)` 準備要存放在快取中的物件。 傳回要存放在快取中的物件。 ## get `Object get(final Object cachedObject)` 從快取的物件中衍生物件。 傳回要從快取傳回的物件 # 使用 JDBC 搭配 AWS Secrets Manager 秘密中的登入資料連線至 SQL 資料庫 在 Java 應用程式中，您可以使用 Secrets Manager SQL Connection 驅動程式，使用存放在 Secrets Manager 中的登入資料連線至 MySQL、PostgreSQL、Oracle、MSSQLServer、Db2 和 Redshift 資料庫。每個驅動程式都會包裝基本 JDBC 驅動程式，因此您可以使用 JDBC 呼叫來存取資料庫。但是，並非傳遞用於連線的使用者名稱和密碼，而是提供機密的 ID。該驅動程式調用機密管理員擷取機密值，然後使用機密中的憑證連線至資料庫。驅動程式還使用 [Java 用戶端快取庫](retrieving-secrets_cache-java.md)快取憑證，因此未來的連線不需要呼叫 Secrets Manager。預設快取每小時重新整理一次機密，並在輪換機密時重新整理一次。若要設定快取，請參閱 [SecretCacheConfiguration](retrieving-secrets_cache-java-ref_SecretCacheConfiguration.md)。 您可以從 [GitHub](https://github.com/aws/aws-secretsmanager-jdbc ) 下載開放原始碼。 使用機密管理員 SQL 連線驅動程式： + 您的應用程式必須使用 Java 8 或更高版本。 + 您的機密必須為下列之一： + [預期 JSON 結構中的資料庫機密](reference_secret_json_structure.md)。若要查看該格式，請在機密管理員控制台中檢視您的機密，然後選擇 **Retrieve secret value** (擷取機密值)。或者，在 中 AWS CLI呼叫 [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html)。 + Amazon RDS [受管機密](integrating_how-services-use-secrets_RDS.md)。對於此類型的機密，您必須在建立連線時指定端點和連接埠。 + Amazon Redshift [受管秘密](integrating_how-services-use-secrets_RS.md)。對於此類型的機密，您必須在建立連線時指定端點和連接埠。 如果要將您的資料庫複製到其他區域，以連線到另一個區域中的複副本資料庫，請在建立連線時指定區域端點和端口。您可以將區域連線資訊作為額外的金鑰/值對、SSM 參數儲存參數或程式碼設定中儲存至機密中。 若要將驅動程式新增至您的專案中，請在 Maven 建置檔案 `pom.xml` 中，為驅動程式新增以下相依性。如需詳細資訊，請參閱 Maven Central Repository 網站上的 [Secrets Manager SQL 連線庫](https://search.maven.org/artifact/com.amazonaws.secretsmanager/aws-secretsmanager-jdbc)。 ``` com.amazonaws.secretsmanager aws-secretsmanager-jdbc 1.0.12 ``` 此驅動程式使用[https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html)。如果您在 Amazon EKS 上執行驅動程式，則其可能會取得正在執行之節點的憑證，而不是服務帳戶角色。為瞭解決此問題，請將 `com.amazonaws:aws-java-sdk-sts` 的版本 1 新增至 Gradle 或 Maven 專案檔案作為相依性。 若要在 `secretsmanager.properties` 檔案中設定 AWS PrivateLink DNS 端點 URL 和區域： ``` drivers.vpcEndpointUrl = endpoint URL drivers.vpcEndpointRegion = endpoint region ``` 若要覆寫主要區域，請設定 `AWS_SECRET_JDBC_REGION` 環境變數或對 `secretsmanager.properties` 檔案進行下列變更： ``` drivers.region = region ``` **必要許可：** + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需詳細資訊，請參閱[許可參考](auth-and-access.md#reference_iam-permissions)。 **Topics** + [建立與資料庫的連線](#retrieving-secrets_jdbc_example) + [透過指定端點和連接埠來建立連線](#retrieving-secrets_jdbc_example_replica) + [使用 c3p0 連線集區建立連線](#retrieving-secrets_jdbc_example_c3po) + [使用 c3p0 連線集區透過指定端點和連接埠來建立連線](#retrieving-secrets_jdbc_example_c3p0_replica) ## 建立與資料庫的連線 以下範例顯示如何使用機密中的憑證和連線資訊建立與資料庫的連線。連線後，您就可使用 JDBC 呼叫來存取資料庫。如需詳細資訊，請參閱 Java 文件網站上的 [JDBC 基礎知識](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html)。 ------ #### [ MySQL ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver" ).newInstance(); // Retrieve the connection info from the secret using the secret ARN String URL = "secretId"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ PostgreSQL ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver" ).newInstance(); // Retrieve the connection info from the secret using the secret ARN String URL = "secretId"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ Oracle ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver" ).newInstance(); // Retrieve the connection info from the secret using the secret ARN String URL = "secretId"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ MSSQLServer ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver" ).newInstance(); // Retrieve the connection info from the secret using the secret ARN String URL = "secretId"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ Db2 ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerDb2Driver" ).newInstance(); // Retrieve the connection info from the secret using the secret ARN String URL = "secretId"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ Redshift ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerRedshiftDriver" ).newInstance(); // Retrieve the connection info from the secret using the secret ARN String URL = "secretId"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ ## 透過指定端點和連接埠來建立連線 下列範例顯示如何使用機密中的憑證與您指定的端點和連接埠建立資料庫的連線。 [Amazon RDS 受管機密](integrating_how-services-use-secrets_RDS.md)不包括資料庫的端點和連接埠。若要使用 Amazon RDS 管理之機密中的主要憑證連線至資料庫，請在程式碼中指定這些憑證。 [複製到其他區域的機密](replicate-secrets.md)可以改善區域資料庫連線的延遲，但其不包含與來源機密不同的連線資訊。每個複本都是來源機密的副本。若要在機密中儲存區域連線資訊，請為區域的端點和端口資訊新增更多金鑰/值對。 連線後，您就可使用 JDBC 呼叫來存取資料庫。如需詳細資訊，請參閱 Java 文件網站上的 [JDBC 基礎知識](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html)。 ------ #### [ MySQL ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:mysql://example.com:3306"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ PostgreSQL ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:postgresql://example.com:5432/database"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ Oracle ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:oracle:thin:@example.com:1521/ORCL"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ MSSQLServer ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:sqlserver://example.com:1433"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ Db2 ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.com.rproxy.govskope.ca.amazonaws.secretsmanager.sql.AWSSecretsManagerDb2Driver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:db2://example.com:50000"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ #### [ Redshift ] ``` // Load the JDBC driver Class.forName( "com.amazonaws.com.rproxy.govskope.ca.amazonaws.secretsmanager.sql.AWSSecretsManagerRedshiftDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:redshift://example.com:5439"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId" ); // Establish the connection conn = DriverManager.getConnection(URL, info); ``` ------ ## 使用 c3p0 連線集區建立連線 下列範例顯示如何使用 `c3p0.properties` 檔案建立連線集區，此檔案使用驅動程式透過機密擷取憑證和連線資訊。對於 `user` 和 `jdbcUrl`，輸入機密 ID 以設定連線集區。然後，您可以從集區中擷取連線並將其用作任何其他資料庫連線。如需詳細資訊，請參閱 Java 文件網站上的 [JDBC 基礎知識](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html)。 如需 c3p0 的詳細資訊，請參閱 Machinery For Change 網站上的 [c3p0](https://www.mchange.com/projects/c3p0/)。 ------ #### [ MySQL ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver c3p0.jdbcUrl=secretId ``` ------ #### [ PostgreSQL ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver c3p0.jdbcUrl=secretId ``` ------ #### [ Oracle ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver c3p0.jdbcUrl=secretId ``` ------ #### [ MSSQLServer ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver c3p0.jdbcUrl=secretId ``` ------ #### [ Db2 ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerDb2Driver c3p0.jdbcUrl=secretId ``` ------ #### [ Redshift ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerRedshiftDriver c3p0.jdbcUrl=secretId ``` ------ ## 使用 c3p0 連線集區透過指定端點和連接埠來建立連線 下列範例說明如何使用 檔案建立連線集區，該`c3p0.properties`檔案使用 驅動程式，以您指定的端點和連接埠擷取秘密中的登入資料。然後，您可以從集區中擷取連線並將其用作任何其他資料庫連線。如需詳細資訊，請參閱 Java 文件網站上的 [JDBC 基礎知識](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html)。 [Amazon RDS 受管機密](integrating_how-services-use-secrets_RDS.md)不包括資料庫的端點和連接埠。若要使用 Amazon RDS 管理之機密中的主要憑證連線至資料庫，請在程式碼中指定這些憑證。 [複製到其他區域的機密](replicate-secrets.md)可以改善區域資料庫連線的延遲，但其不包含與來源機密不同的連線資訊。每個複本都是來源機密的副本。若要在機密中儲存區域連線資訊，請為區域的端點和端口資訊新增更多金鑰/值對。 ------ #### [ MySQL ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver c3p0.jdbcUrl=jdbc-secretsmanager:mysql://example.com:3306 ``` ------ #### [ PostgreSQL ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver c3p0.jdbcUrl=jdbc-secretsmanager:postgresql://example.com:5432/database ``` ------ #### [ Oracle ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver c3p0.jdbcUrl=jdbc-secretsmanager:oracle:thin:@example.com:1521/ORCL ``` ------ #### [ MSSQLServer ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver c3p0.jdbcUrl=jdbc-secretsmanager:sqlserver://example.com:1433 ``` ------ #### [ Db2 ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerDb2Driver c3p0.jdbcUrl=jdbc-secretsmanager:db2://example.com:50000 ``` ------ #### [ Redshift ] ``` c3p0.user=secretId c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerRedshiftDriver c3p0.jdbcUrl=jdbc-secretsmanager:redshift://example.com:5439 ``` ------ # 使用 Java AWS 開發套件取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 + 如果將資料庫憑證存放在秘密中，則請使用 [Secrets Manager SQL 連線驅動程式](retrieving-secrets_jdbc.md)，以使用秘密中的憑證連線至資料庫。 + 對於其他類型的秘密，請使用 [Secrets Manager Java 型快取元件，](retrieving-secrets_cache-java.md)或使用 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/model/GetSecretValueResult.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/model/GetSecretValueResult.html)或 直接呼叫 SDK[https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/model/BatchGetSecretValueResult.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/secretsmanager/model/BatchGetSecretValueResult.html)。 下列程式碼範例示範如何使用 `GetSecretValue`。 **必要許可：**`secretsmanager:GetSecretValue` ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.secretsmanager.SecretsManagerClient; import software.amazon.awssdk.services.secretsmanager.model.GetSecretValueRequest; import software.amazon.awssdk.services.secretsmanager.model.GetSecretValueResponse; import software.amazon.awssdk.services.secretsmanager.model.SecretsManagerException; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html * * We recommend that you cache your secret values by using client-side caching. * * Caching secrets improves speed and reduces your costs. For more information, * see the following documentation topic: * * https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html */ public class GetSecretValue { public static void main(String[] args) { final String usage = """ Usage: \s Where: secretName - The name of the secret (for example, tutorials/MyFirstSecret).\s """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String secretName = args[0]; Region region = Region.US_EAST_1; SecretsManagerClient secretsClient = SecretsManagerClient.builder() .region(region) .build(); getValue(secretsClient, secretName); secretsClient.close(); } public static void getValue(SecretsManagerClient secretsClient, String secretName) { try { GetSecretValueRequest valueRequest = GetSecretValueRequest.builder() .secretId(secretName) .build(); GetSecretValueResponse valueResponse = secretsClient.getSecretValue(valueRequest); String secret = valueResponse.secretString(); System.out.println(secret); } catch (SecretsManagerException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } } ``` # 使用 Python 取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 **Topics** + [使用 Python 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-python.md) + [使用 Python AWS SDK 取得 Secrets Manager 秘密值](retrieving-secrets-python-sdk.md) + [使用 Python AWS SDK 取得一批 Secrets Manager 秘密值](retrieving-secrets-python-batch.md) # 使用 Python 搭配用戶端快取取得 Secrets Manager 秘密值 擷取秘密時，您可以使用 Secrets Manager Python 型快取元件進行快取以供將來使用。擷取快取的秘密比從 Secrets Manager 中擷取要快。由於呼叫 Secrets Manager API 需要花費成本，因此使用快取可以降低成本。如需您可以擷取機密的所有方法，請參閱 [取得秘密](retrieving-secrets.md)。 快取政策是「最近最少使用的 (LRU)」，因此當快取必須丟棄秘密時，其會丟棄最近最少使用的秘密。預設情況下，快取每小時重新整理一次秘密。您可以設定在快取中[重新整理機密的頻率](retrieving-secrets_cache-ref-secretcacheconfig.md)，並可以[掛接到機密擷取](retrieving-secrets_cache-ref-secretcachehook.md)以新增更多功能。 一旦釋放快取參考，快取不會強制執行垃圾回收。快取實作不包括快取失效。快取實作著重於快取本身，而不是強化或著重於安全性。如果您需要額外的安全性，例如加密快取中的項目，請使用提供的介面和抽象方法。 若要使用元件，您必須擁有下列項目： + Python 3.6 或更高版本。 + botocore 1.12 或更高版本。請參閱 [AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) 和 [Botocore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html)。 + setuptools\$1scm 3.2 或更高版本。請參閱 [https://pypi.org/project/setuptools-scm/](https://pypi.org/project/setuptools-scm/)。 若要下載開放程式碼，請參閱 [Secrets Manager Python 型快取用戶端元件](https://github.com/aws/aws-secretsmanager-caching-python ) (在 GitHub 上)。 若要安裝元件，請使用下列命令。 ``` $ pip install aws-secretsmanager-caching ``` **必要許可：** + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需詳細資訊，請參閱[許可參考](auth-and-access.md#reference_iam-permissions)。 **Topics** + [SecretCache](retrieving-secrets_cache-ref-secretcache.md) + [SecretCacheConfig](retrieving-secrets_cache-ref-secretcacheconfig.md) + [SecretCacheHook](retrieving-secrets_cache-ref-secretcachehook.md) + [@InjectSecretString](retrieving-secrets_cache-decor-string.md) + [@InjectKeywordedSecretString](retrieving-secrets_cache-decor-keyword.md) **Example 擷取秘密** 以下範例顯示如何為名為 *mysecret* 的秘密取得秘密值。 ``` import botocore import botocore.session from aws_secretsmanager_caching import SecretCache, SecretCacheConfig client = botocore.session.get_session().create_client('secretsmanager') cache_config = SecretCacheConfig() cache = SecretCache( config = cache_config, client = client) secret = cache.get_secret_string('mysecret') ``` # SecretCache 從 Secrets Manager 擷取的秘密記憶體內快取。您使用 [get\$1secret\$1string](#retrieving-secrets_cache-ref-secretcache_get_secret_string) 或 [get\$1secret\$1binary](#retrieving-secrets_cache-ref-secretcache_get_secret_binary) 從快取中擷取秘密。您可以透過在建構函式的 [SecretCacheConfig](retrieving-secrets_cache-ref-secretcacheconfig.md) 物件中傳遞，設定快取設定。 如需包含範例的詳細資訊，請參閱 [使用 Python 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-python.md)。 ``` cache = SecretCache( config = SecretCacheConfig, client = [client](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html) ) ``` **Topics** + [get\$1secret\$1string](#retrieving-secrets_cache-ref-secretcache_get_secret_string) + [get\$1secret\$1binary](#retrieving-secrets_cache-ref-secretcache_get_secret_binary) ## get\$1secret\$1string 擷取秘密字串值。 請求語法 ``` response = cache.get_secret_string( secret_id='string', version_stage='string' ) ``` Parameters + `secret_id` (*字串*)：【必要】 秘密的名稱或 ARN。 + `version_stage` (*字串*)：您要擷取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md)。預設值為 'AWSCURRENT'。 傳回類型 string ## get\$1secret\$1binary 擷取秘密二進位值。 請求語法 ``` response = cache.get_secret_binary( secret_id='string', version_stage='string' ) ``` Parameters + `secret_id` (*字串*)：【必要】 秘密的名稱或 ARN。 + `version_stage` (*字串*)：您要擷取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md)。預設值為 'AWSCURRENT'。 傳回類型 [base64-encoded](https://tools.ietf.org/html/rfc4648#section-4) 字串 # SecretCacheConfig [SecretCache](retrieving-secrets_cache-ref-secretcache.md) 的快取組態選項，例如最大快取大小和快取秘密的存留時間 (TTL)。Parameters `max_cache_size` (*int*) 最大快取大小。預設值為 `1024` 個秘密。 `exception_retry_delay_base` (*int*) 重試請求前遇到異常之後等待的秒數。預設值為 `1`。 `exception_retry_growth_factor` (*int*)pur 用於計算失敗請求重試之間等待時間的增長係數。預設值為 `2`。 `exception_retry_delay_max` (*int*) 在失敗請求之間等待的時間上限 (以秒為單位)。預設值為 `3600`。 `default_version_stage` (*str*) 要快取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。預設為 `'AWSCURRENT'`。 `secret_refresh_interval` (*int*) 重新整理快取秘密資訊之間的等待秒數。預設值為 `3600`。 `secret_cache_hook` (*SecretCacheHook*) `SecretCacheHook` 摘要類別的實作。預設值為 `None`。 # SecretCacheHook 用於掛接到 [SecretCache](retrieving-secrets_cache-ref-secretcache.md)，以對存放在快取中的秘密執行動作的介面。 **Topics** + [put](#retrieving-secrets_cache-ref-secretcachehook_put) + [get](#retrieving-secrets_cache-ref-secretcachehook_get) ## put 準備要存放在快取中的物件。 請求語法 ``` response = hook.put( obj='secret_object' ) ``` Parameters + `obj` (*物件*) – [必需] 包含秘密的秘密或物件。 傳回類型 object ## get 從快取的物件中衍生物件。 請求語法 ``` response = hook.get( obj='secret_object' ) ``` Parameters + `obj` (*物件*)：【必要】 包含秘密的秘密或物件。 傳回類型 object # @InjectSecretString 此裝飾項目需要秘密 ID 字串和 [SecretCache](retrieving-secrets_cache-ref-secretcache.md) 作為第一個和第二個引數。裝飾項目傳回秘密字串值。秘密必須包含字串。 ``` from aws_secretsmanager_caching import SecretCache from aws_secretsmanager_caching import InjectKeywordedSecretString, InjectSecretString cache = SecretCache() @InjectSecretString ( 'mysecret' , cache ) def function_to_be_decorated( arg1, arg2, arg3): ``` # @InjectKeywordedSecretString 此裝飾項目需要秘密 ID 字串和 [SecretCache](retrieving-secrets_cache-ref-secretcache.md) 作為第一個和第二個引數。剩餘的引數將參數從包裝函數映射到秘密中的 JSON 金鑰。秘密必須包含 JSON 結構中的字串。 對於包含此 JSON 的秘密： ``` { "username": "saanvi", "password": "EXAMPLE-PASSWORD" } ``` 下列範例顯示如何從秘密擷取 `username` 和 `password` 的 JSON 值。 ``` from aws_secretsmanager_caching import SecretCache from aws_secretsmanager_caching import InjectKeywordedSecretString, InjectSecretString cache = SecretCache() @InjectKeywordedSecretString ( secret_id = 'mysecret' , cache = cache , func_username = 'username' , func_password = 'password' ) def function_to_be_decorated( func_username, func_password): print( 'Do something with the func_username and func_password parameters') ``` # 使用 Python AWS SDK 取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 對於 Python 應用程式，請使用 [Secrets Manager Python 型快取元件](retrieving-secrets_cache-python.md)或使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/get_secret_value.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/get_secret_value.html) 或 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/batch_get_secret_value.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/batch_get_secret_value.html) 直接呼叫 SDK。 下列程式碼範例示範如何使用 `GetSecretValue`。 **必要許可：**`secretsmanager:GetSecretValue` ``` """ Purpose Shows how to use the AWS SDK for Python (Boto3) with AWS Secrets Manager to get a specific of secrets that match a specified name """ import boto3 import logging from get_secret_value import GetSecretWrapper # Configure logging logging.basicConfig(level=logging.INFO) def run_scenario(secret_name): """ Retrieve a secret from AWS Secrets Manager. :param secret_name: Name of the secret to retrieve. :type secret_name: str """ try: # Validate secret_name if not secret_name: raise ValueError("Secret name must be provided.") # Retrieve the secret by name client = boto3.client("secretsmanager") wrapper = GetSecretWrapper(client) secret = wrapper.get_secret(secret_name) # Note: Secrets should not be logged. return secret except Exception as e: logging.error(f"Error retrieving secret: {e}") raise class GetSecretWrapper: def __init__(self, secretsmanager_client): self.client = secretsmanager_client def get_secret(self, secret_name): """ Retrieve individual secrets from AWS Secrets Manager using the get_secret_value API. This function assumes the stack mentioned in the source code README has been successfully deployed. This stack includes 7 secrets, all of which have names beginning with "mySecret". :param secret_name: The name of the secret fetched. :type secret_name: str """ try: get_secret_value_response = self.client.get_secret_value( SecretId=secret_name ) logging.info("Secret retrieved successfully.") return get_secret_value_response["SecretString"] except self.client.exceptions.ResourceNotFoundException: msg = f"The requested secret {secret_name} was not found." logger.info(msg) return msg except Exception as e: logger.error(f"An unknown error occurred: {str(e)}.") raise ``` # 使用 Python AWS SDK 取得一批 Secrets Manager 秘密值 下列程式碼範例示範如何取得 Secrets Manager 秘密值的批次。 **必要許可：** + `secretsmanager:BatchGetSecretValue` + `secretsmanager:GetSecretValue` 您要擷取之每個秘密的 許可。 + 如果您使用過濾器，則還必須擁有 `secretsmanager:ListSecrets`。 如需許可政策範例，請參閱 [範例：擷取批次中一組秘密值的許可](auth-and-access_iam-policies.md#auth-and-access_examples_batch)。 **重要** 如果您的 VPCE 原則拒絕擷取您要擷取之群組中個別密碼的權限，則 `BatchGetSecretValue` 不會傳回任何秘密值，而且會傳回錯誤。 ``` class BatchGetSecretsWrapper: def __init__(self, secretsmanager_client): self.client = secretsmanager_client def batch_get_secrets(self, filter_name): """ Retrieve multiple secrets from AWS Secrets Manager using the batch_get_secret_value API. This function assumes the stack mentioned in the source code README has been successfully deployed. This stack includes 7 secrets, all of which have names beginning with "mySecret". :param filter_name: The full or partial name of secrets to be fetched. :type filter_name: str """ try: secrets = [] response = self.client.batch_get_secret_value( Filters=[{"Key": "name", "Values": [f"{filter_name}"]}] ) for secret in response["SecretValues"]: secrets.append(json.loads(secret["SecretString"])) if secrets: logger.info("Secrets retrieved successfully.") else: logger.info("Zero secrets returned without error.") return secrets except self.client.exceptions.ResourceNotFoundException: msg = f"One or more requested secrets were not found with filter: {filter_name}" logger.info(msg) return msg except Exception as e: logger.error(f"An unknown error occurred:\n{str(e)}.") raise ``` # 使用 取得 Secrets Manager 秘密值 .NET 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 **Topics** + [使用具有用戶端快取的 .NET 取得 Secrets Manager 秘密值](retrieving-secrets_cache-net.md) + [使用 取得 Secrets Manager 秘密值 適用於 .NET 的 SDK](retrieving-secrets-net-sdk.md) # 使用具有用戶端快取的 .NET 取得 Secrets Manager 秘密值 擷取秘密時，您可以使用 Secrets Manager .NET 型快取元件進行快取以供將來使用。擷取快取的秘密比從 Secrets Manager 中擷取要快。由於呼叫 Secrets Manager API 需要花費成本，因此使用快取可以降低成本。如需您可以擷取機密的所有方法，請參閱 [取得秘密](retrieving-secrets.md)。 快取政策是「最近最少使用的 (LRU)」，因此當快取必須丟棄秘密時，其會丟棄最近最少使用的秘密。預設情況下，快取每小時重新整理一次秘密。您可以設定在快取中[重新整理機密的頻率](retrieving-secrets_cache-net-SecretCacheConfiguration.md#retrieving-secrets_cache-net-SecretCacheConfiguration-properties_CacheItemTTL)，並可以[掛接到機密擷取](retrieving-secrets_cache-net-ISecretCacheHook.md)以新增更多功能。 一旦釋放快取參考，快取不會強制執行垃圾回收。快取實作不包括快取失效。快取實作著重於快取本身，而不是強化或著重於安全性。如果您需要額外的安全性，例如加密快取中的項目，請使用提供的介面和抽象方法。 若要使用元件，您必須擁有下列項目： + .NET Framework 4.6.2 或更新版本，或 .NET Standard 2.0 或更新版本。請參閱 Microsoft 網站上的[下載 .NET](https://dotnet.microsoft.com/en-us/download)。 + 適用於 .NET 的 AWS SDK。請參閱 [AWS SDKs](asm_access.md#asm-sdks)。 若要下載開放程式碼，請參閱 [.NET 快取用戶端](https://github.com/aws/aws-secretsmanager-caching-net ) (在 GitHub 上)。 若要使用快取，請首先讓其成為執行個體，然後使用 `GetSecretString` 或 `GetSecretBinary` 擷取。在連續擷取時，快取會傳回秘密的快取複本。 **若要取得快取套件** + 執行以下任意一項： + 在您的專案目錄中，執行下列 .NET CLI 命令。 ``` dotnet add package AWSSDK.SecretsManager.Caching --version 1.0.6 ``` + 將以下套件參考新增至您的 `.csproj` 檔案中。 ``` ``` **必要許可：** + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需詳細資訊，請參閱[許可參考](auth-and-access.md#reference_iam-permissions)。 **Topics** + [SecretsManagerCache](retrieving-secrets_cache-net-SecretsManagerCache.md) + [SecretCacheConfiguration](retrieving-secrets_cache-net-SecretCacheConfiguration.md) + [ISecretCacheHook](retrieving-secrets_cache-net-ISecretCacheHook.md) **Example 擷取秘密** 下列程式碼範例顯示擷取名為 *MySecret* 之秘密的方式。 ``` using Amazon.SecretsManager.Extensions.Caching; namespace LambdaExample { public class CachingExample { private const string MySecretName ="MySecret"; private SecretsManagerCache cache = new SecretsManagerCache(); public async Task FunctionHandlerAsync(string input, ILambdaContext context) { string MySecret = await cache.GetSecretString(MySecretName); // Use the secret, return success } } } ``` **Example 設定存留時間 (TTL) 快取重新整理持續時間** 下列程式碼範例說明擷取名為 *MySecret* 的秘密，並將 TTL 快取重新整理持續時間設定為 24 小時的方式。 ``` using Amazon.SecretsManager.Extensions.Caching; namespace LambdaExample { public class CachingExample { private const string MySecretName = "MySecret"; private static SecretCacheConfiguration cacheConfiguration = new SecretCacheConfiguration { CacheItemTTL = 86400000 }; private SecretsManagerCache cache = new SecretsManagerCache(cacheConfiguration); public async Task FunctionHandlerAsync(string input, ILambdaContext context) { string mySecret = await cache.GetSecretString(MySecretName); // Use the secret, return success } } } ``` # SecretsManagerCache 從 Secrets Manager 請求的秘密記憶體內快取。您使用 [GetSecretString](#retrieving-secrets_cache-net-SecretsManagerCache-methods-GetSecretString) 或 [GetSecretBinary](#retrieving-secrets_cache-net-SecretsManagerCache-methods-GetSecretBinary) 從快取中擷取秘密。您可以透過在建構函式的 [SecretCacheConfiguration](retrieving-secrets_cache-net-SecretCacheConfiguration.md) 物件中傳遞，設定快取設定。 如需包含範例的詳細資訊，請參閱 [使用具有用戶端快取的 .NET 取得 Secrets Manager 秘密值](retrieving-secrets_cache-net.md)。 ## 建構函式 `public SecretsManagerCache()` `SecretsManagerCache` 物件的預設建構函式。 `public SecretsManagerCache(IAmazonSecretsManager secretsManager)` 使用以提供的 [AmazonSecretsManagerClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TSecretsManagerClient.html) 建立的 Secrets Manager 用戶端建構新快取。使用此建構函式可以自訂 Secrets Manager 用戶端，例如使用特定區域或端點。 **Parameters** secretsManager 從中擷取秘密的 [AmazonSecretsManagerClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TSecretsManagerClient.html)。 `public SecretsManagerCache(SecretCacheConfiguration config)` 使用提供的 [SecretCacheConfiguration](retrieving-secrets_cache-net-SecretCacheConfiguration.md) 建構新的秘密快取。使用此建構函式設定快取，例如要快取的秘密數量及其重新整理的頻率。 **Parameters** config 包含快取組態資訊的 [SecretCacheConfiguration](retrieving-secrets_cache-net-SecretCacheConfiguration.md)。 `public SecretsManagerCache(IAmazonSecretsManager secretsManager, SecretCacheConfiguration config)` 使用以提供的 [AmazonSecretsManagerClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TSecretsManagerClient.html) 和 [SecretCacheConfiguration](retrieving-secrets_cache-net-SecretCacheConfiguration.md) 建立的 Secrets Manager 用戶端建構新快取。使用此建構函式可以自訂 SSecrets Manager 用戶端，例如，使用特定區域或端點並設定快取，例如要快取的秘密數量及其重新整理的頻率。 **Parameters** secretsManager 從中擷取秘密的 [AmazonSecretsManagerClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TSecretsManagerClient.html)。 config 包含快取組態資訊的 [SecretCacheConfiguration](retrieving-secrets_cache-net-SecretCacheConfiguration.md)。 ## 方法 ### GetSecretString `public async Task GetSecretString(String secretId)` 從 Secrets Manager 中擷取字串秘密。Parameters secretId 要擷取之秘密的 ARN 或名稱。 ### GetSecretBinary `public async Task GetSecretBinary(String secretId)` 從 Secrets Manager 中擷取二進位秘密。Parameters secretId 要擷取之秘密的 ARN 或名稱。 ### RefreshNowAsync `public async Task RefreshNowAsync(String secretId)` 請求 Secrets Manager 的秘密值，並使用任何變更來更新快取。如果沒有現有的快取項目，則請建立一個新的。如果重新整理成功，則會傳回 `true`。Parameters secretId 要擷取之秘密的 ARN 或名稱。 ### GetCachedSecret `public SecretCacheItem GetCachedSecret(string secretId)` 如果存在於快取中，則傳回指定秘密的快取項目。否則，從 Secrets Manager 中擷取秘密並建立新的快取項目。Parameters secretId 要擷取之秘密的 ARN 或名稱。 # SecretCacheConfiguration [SecretsManagerCache](retrieving-secrets_cache-net-SecretsManagerCache.md) 的快取組態選項，例如最大快取大小和快取秘密的存留時間 (TTL)。 ## Properties ### CacheItemTTL `public uint CacheItemTTL { get; set; }` 快取項目的 TTL (以毫秒為單位)。預設值為 `3600000` 毫秒或 1 小時。上限為 `4294967295` 毫秒，大約為 49.7 天。 ### MaxCacheSize `public ushort MaxCacheSize { get; set; }` 最大快取大小。預設值為 1024 個秘密。最多 65,535 個。 ### VersionStage `public string VersionStage { get; set; }` 要快取的秘密版本。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。預設為 `"AWSCURRENT"`。 ### 用戶端 `public IAmazonSecretsManager Client { get; set; }` 從中擷取秘密的 [AmazonSecretsManagerClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TSecretsManagerClient.html)。如果是 `null`，則快取會執行個體化一個新的用戶端。預設值為 `null`。 ### CacheHook `public ISecretCacheHook CacheHook { get; set; }` [ISecretCacheHook](retrieving-secrets_cache-net-ISecretCacheHook.md)。 # ISecretCacheHook 用於掛接到 [SecretsManagerCache](retrieving-secrets_cache-net-SecretsManagerCache.md)，以對存放在快取中的秘密執行動作的介面。 ## 方法 ### 放置 `object Put(object o);` 準備要存放在快取中的物件。 傳回要存放在快取中的物件。 ### 取得 `object Get(object cachedObject);` 從快取的物件中衍生物件。 傳回要從快取傳回的物件 # 使用 取得 Secrets Manager 秘密值 適用於 .NET 的 SDK 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 對於 .NET 應用程式，請使用 [Secrets Manager .NET 型快取元件](retrieving-secrets_cache-net.md)或使用 [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TGetSecretValueRequest.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TGetSecretValueRequest.html) 或 [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TBatchGetSecretValueRequest.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SecretsManager/TBatchGetSecretValueRequest.html) 直接呼叫 SDK。 下列程式碼範例示範如何使用 `GetSecretValue`。 **必要許可：**`secretsmanager:GetSecretValue` ``` using System; using System.IO; using System.Threading.Tasks; using Amazon.SecretsManager; using Amazon.SecretsManager.Model; /// /// This example uses the Amazon Web Service Secrets Manager to retrieve /// the secret value for the provided secret name. /// public class GetSecretValue { /// /// The main method initializes the necessary values and then calls /// the GetSecretAsync and DecodeString methods to get the decoded /// secret value for the secret named in secretName. /// public static async Task Main() { string secretName = "<<{{MySecretName}}>>"; string secret; IAmazonSecretsManager client = new AmazonSecretsManagerClient(); var response = await GetSecretAsync(client, secretName); if (response is not null) { secret = DecodeString(response); if (!string.IsNullOrEmpty(secret)) { Console.WriteLine($"The decoded secret value is: {secret}."); } else { Console.WriteLine("No secret value was returned."); } } } /// /// Retrieves the secret value given the name of the secret to /// retrieve. /// /// The client object used to retrieve the secret /// value for the given secret name. /// The name of the secret value to retrieve. /// The GetSecretValueReponse object returned by /// GetSecretValueAsync. public static async Task GetSecretAsync( IAmazonSecretsManager client, string secretName) { GetSecretValueRequest request = new GetSecretValueRequest() { SecretId = secretName, VersionStage = "AWSCURRENT", // VersionStage defaults to AWSCURRENT if unspecified. }; GetSecretValueResponse response = null; // For the sake of simplicity, this example handles only the most // general SecretsManager exception. try { response = await client.GetSecretValueAsync(request); } catch (AmazonSecretsManagerException e) { Console.WriteLine($"Error: {e.Message}"); } return response; } /// /// Decodes the secret returned by the call to GetSecretValueAsync and /// returns it to the calling program. /// /// A GetSecretValueResponse object containing /// the requested secret value returned by GetSecretValueAsync. /// A string representing the decoded secret value. public static string DecodeString(GetSecretValueResponse response) { // Decrypts secret using the associated AWS Key Management Service // Customer Master Key (CMK.) Depending on whether the secret is a // string or binary value, one of these fields will be populated. if (response.SecretString is not null) { var secret = response.SecretString; return secret; } else if (response.SecretBinary is not null) { var memoryStream = response.SecretBinary; StreamReader reader = new StreamReader(memoryStream); string decodedBinarySecret = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(reader.ReadToEnd())); return decodedBinarySecret; } else { return string.Empty; } } } ``` # 使用 Go 取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 **Topics** + [使用 Go 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-go.md) + [使用 Go AWS 開發套件取得 Secrets Manager 秘密值](retrieving-secrets-go-sdk.md) # 使用 Go 搭配用戶端快取取得 Secrets Manager 秘密值 擷取秘密時，您可以使用 Secrets Manager Go 型快取元件進行快取以供將來使用。擷取快取的秘密比從 Secrets Manager 中擷取要快。由於呼叫 Secrets Manager API 需要花費成本，因此使用快取可以降低成本。如需您可以擷取機密的所有方法，請參閱 [取得秘密](retrieving-secrets.md)。 快取政策是「最近最少使用的 (LRU)」，因此當快取必須丟棄秘密時，其會丟棄最近最少使用的秘密。預設情況下，快取每小時重新整理一次秘密。您可以設定在快取中[重新整理機密的頻率](retrieving-secrets_cache-go_CacheConfig.md)，並可以[掛接到機密擷取](retrieving-secrets_cache-go_CacheHook.md)以新增更多功能。 一旦釋放快取參考，快取不會強制執行垃圾回收。快取實作不包括快取失效。快取實作著重於快取本身，而不是強化或著重於安全性。如果您需要額外的安全性，例如加密快取中的項目，請使用提供的介面和抽象方法。 若要使用元件，您必須擁有下列項目： + AWS 適用於 Go 的 SDK。請參閱 [AWS SDKs](asm_access.md#asm-sdks)。 若要下載開放程式碼，請參閱 [Secrets Manager Go 快取用戶端](https://github.com/aws/aws-secretsmanager-caching-go ) (在 GitHub 上)。 若要設定 Go 開發環境，請參閱 Go 程式設計語言網站上的 [Golang 入門](https://golang.org/doc/install)。 **必要許可：** + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需詳細資訊，請參閱[許可參考](auth-and-access.md#reference_iam-permissions)。 **Topics** + [輸入 Cache](retrieving-secrets_cache-go_cache.md) + [輸入 CacheConfig](retrieving-secrets_cache-go_CacheConfig.md) + [輸入 CacheHook](retrieving-secrets_cache-go_CacheHook.md) **Example 擷取秘密** 下列程式碼範例顯示擷取秘密的 Lambda 函數。 ``` package main import ( "github.com/aws/aws-lambda-go/lambda" "github.com/aws/aws-secretsmanager-caching-go/secretcache" ) var ( secretCache, _ = secretcache.New() ) func HandleRequest(secretId string) string { result, _ := secretCache.GetSecretString(secretId) // Use the secret, return success } func main() { lambda. Start( HandleRequest) } ``` # 輸入 Cache 從 Secrets Manager 請求的秘密記憶體內快取。您使用 [GetSecretString](#retrieving-secrets_cache-go_cache_operations_GetCachedSecret) 或 [GetSecretBinary](#retrieving-secrets_cache-go_cache_operations_GetSecretBinary) 從快取中擷取秘密。 下列範例顯示如何設定快取設定。 ``` // Create a custom secretsmanager client client := getCustomClient() // Create a custom CacheConfig struct config := secretcache. CacheConfig{ MaxCacheSize: secretcache.DefaultMaxCacheSize + 10, VersionStage: secretcache.DefaultVersionStage, CacheItemTTL: secretcache.DefaultCacheItemTTL, } // Instantiate the cache cache, _ := secretcache.New( func( c *secretcache.Cache) { c. CacheConfig = config }, func( c *secretcache.Cache) { c. Client = client }, ) ``` 如需包含範例的詳細資訊，請參閱 [使用 Go 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-go.md)。 ## 方法 ### 新增 `func New(optFns ...func(*Cache)) (*Cache, error)` 使用功能選項建構新秘密快取，否則使用預設值。從新的工作階段初始化 SecretsManager 用戶端。將 CacheConfig 初始化為預設值。使用預設的最大大小起始 LRU 快取。 ### GetSecretString `func (c *Cache) GetSecretString(secretId string) (string, error)` GetSecretString 從快取中取得秘密字串值，用於指定秘密 ID。如果操作失敗，傳回秘密字串和錯誤。 ### GetSecretStringWithStage `func (c *Cache) GetSecretStringWithStage(secretId string, versionStage string) (string, error)` GetSecretStringWithStage 從快取中取得秘密字串值，用於指定秘密 ID 和[版本階段](whats-in-a-secret.md#term_version)。如果操作失敗，傳回秘密字串和錯誤。 ### GetSecretBinary `func (c *Cache) GetSecretBinary(secretId string) ([]byte, error) {` GetSecretBinary 從快取中取得秘密二進位值，用於指定秘密 ID。如果操作失敗，則傳回秘密二進位和錯誤。 ### GetSecretBinaryWithStage `func (c *Cache) GetSecretBinaryWithStage(secretId string, versionStage string) ([]byte, error)` GetSecretBinaryWithStage 從快取中取得秘密二進位值，用於指定秘密 ID 和[版本階段](whats-in-a-secret.md#term_version)。如果操作失敗，則傳回秘密二進位和錯誤。 # 輸入 CacheConfig [快取](retrieving-secrets_cache-go_cache.md)的快取組態選項，例如最大快取大小、預設[版本階段](whats-in-a-secret.md#term_version)和快取秘密的存留時間 (TTL)。 ``` type CacheConfig struct { // The maximum cache size. The default is 1024 secrets. MaxCacheSize int // The TTL of a cache item in nanoseconds. The default is // 3.6e10^12 ns or 1 hour. CacheItemTTL int64 // The version of secrets that you want to cache. The default // is "AWSCURRENT". VersionStage string // Used to hook in-memory cache updates. Hook CacheHook } ``` # 輸入 CacheHook 用於掛接到[快取](retrieving-secrets_cache-go_cache.md)，以對存放在快取中的秘密執行動作的介面。 ## 方法 ### 放置 `Put(data interface{}) interface{}` 準備要存放在快取中的物件。 ### 取得 `Get(data interface{}) interface{}` 從快取的物件中衍生物件。 # 使用 Go AWS 開發套件取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 對於 Go 應用程式，請使用 [Secrets Manager Go 型快取元件](retrieving-secrets_cache-go.md)或使用 [https://docs.aws.amazon.com/sdk-for-go/api/service/secretsmanager/#SecretsManager.GetSecretValue](https://docs.aws.amazon.com/sdk-for-go/api/service/secretsmanager/#SecretsManager.GetSecretValue) 或 [https://docs.aws.amazon.com/sdk-for-go/api/service/secretsmanager/#SecretsManager.BatchGetSecretValue](https://docs.aws.amazon.com/sdk-for-go/api/service/secretsmanager/#SecretsManager.BatchGetSecretValue) 直接呼叫 SDK。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` // Use this code snippet in your app. // If you need more information about configurations or implementing the sample code, visit the AWS docs: // https://aws.github.io/aws-sdk-go-v2/docs/getting-started/ import ( "context" "log" "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/service/secretsmanager" ) func main() { secretName := "<<{{MySecretName}}>>" region := "<<{{MyRegionName}}>>" config, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion(region)) if err != nil { log.Fatal(err) } // Create Secrets Manager client svc := secretsmanager.NewFromConfig(config) input := &secretsmanager.GetSecretValueInput{ SecretId: aws.String(secretName), VersionStage: aws.String("AWSCURRENT"), // VersionStage defaults to AWSCURRENT if unspecified } result, err := svc.GetSecretValue(context.TODO(), input) if err != nil { // For a list of exceptions thrown, see // https://<<{{DocsDomain}}>>/secretsmanager/latest/apireference/API_GetSecretValue.html log.Fatal(err.Error()) } // Decrypts secret using the associated KMS key. var secretString string = *result.SecretString // Your code goes here. } ``` # 使用 Rust 取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 **Topics** + [使用 Rust 搭配用戶端快取取得 Secrets Manager 秘密值](retrieving-secrets_cache-rust.md) + [使用 Rust AWS SDK 取得 Secrets Manager 秘密值](retrieving-secrets-rust-sdk.md) # 使用 Rust 搭配用戶端快取取得 Secrets Manager 秘密值 擷取秘密時，您可以使用 Secrets Manager Rust 型快取元件來快取秘密以供日後使用。擷取快取的秘密比從 Secrets Manager 中擷取要快。由於呼叫 Secrets Manager API 需要花費成本，因此使用快取可以降低成本。如需您可以擷取機密的所有方法，請參閱 [取得秘密](retrieving-secrets.md)。 快取政策是先進先出 (FIFO)，因此當快取必須捨棄秘密時，會捨棄最舊的秘密。預設情況下，快取每小時重新整理一次秘密。您可以設定下列項目： + `max_size` – 在移出最近未存取的秘密之前，要維護的快取秘密數目上限。 + `ttl` – 在需要重新整理秘密狀態之前，快取項目視為有效的持續時間。 快取實作不包括快取失效。快取實作著重於快取本身，而不是強化或著重於安全性。如果您需要額外的安全性，例如加密快取中的項目，請使用提供的特徵來修改快取。 若要使用 元件，您必須具有具有 的 Rust 2021 開發環境`tokio`。如需詳細資訊，請參閱 Rust 程式設計語言網站上的[入門](https://www.rust-lang.org/learn/get-started)。 若要下載原始程式碼，請參閱 GitHub 上的 [Secrets Manager Rust 型快取用戶端元件](https://github.com/aws/aws-secretsmanager-agent/tree/main/aws_secretsmanager_caching)。 若要安裝快取元件，請使用下列命令。 ``` cargo add aws_secretsmanager_caching ``` **必要許可：** + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需詳細資訊，請參閱[許可參考](auth-and-access.md#reference_iam-permissions)。 **Example 擷取秘密** 下列範例顯示如何取得名為 *MyTest* 之秘密的秘密值。 ``` use aws_secretsmanager_caching::SecretsManagerCachingClient; use std::num::NonZeroUsize; use std::time::Duration; let client = match SecretsManagerCachingClient::default( NonZeroUsize::new(10).unwrap(), Duration::from_secs(60), ) .await { Ok(c) => c, Err(_) => panic!("Handle this error"), }; let secret_string = match client.get_secret_value("MyTest", None, None).await { Ok(s) => s.secret_string.unwrap(), Err(_) => panic!("Handle this error"), }; // Your code here ``` **Example 使用自訂組態和自訂用戶端執行個體化快取** 下列範例示範如何設定快取，然後取得名為 *MyTest* 之秘密的秘密值。 ``` let config = aws_config::load_defaults(BehaviorVersion::latest()) .await .into_builder() .region(Region::from_static("us-west-2")) .build(); let asm_builder = aws_sdk_secretsmanager::config::Builder::from(&config); let client = match SecretsManagerCachingClient::from_builder( asm_builder, NonZeroUsize::new(10).unwrap(), Duration::from_secs(60), ) .await { Ok(c) => c, Err(_) => panic!("Handle this error"), }; let secret_string = client .get_secret_value("MyTest", None, None) .await { Ok(c) => c.secret_string.unwrap(), Err(_) => panic!("Handle this error"), }; // Your code here ``` ``` # 使用 Rust AWS SDK 取得 Secrets Manager 秘密值 在應用程式中，您可以透過在任何 AWS SDKs `BatchGetSecretValue`中呼叫 `GetSecretValue`或 來擷取秘密。不過，建議您使用用戶端快取來快取您的秘密值。快取秘密可提高速度並降低成本。 對於 Rust 應用程式，請使用 [Secrets Manager Rust 型快取元件，](retrieving-secrets_cache-rust.md)或使用 GetSecretValue 或 BatchGetSecretValue [直接呼叫 SDK](https://docs.rs/releases/search?query=aws-sdk-secretsmanager)。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` async fn show_secret(client: &Client, name: &str) -> Result<(), Error> { let resp = client.get_secret_value().secret_id(name).send().await?; println!("Value: {}", resp.secret_string().unwrap_or("No value!")); Ok(()) } ``` # 在 Amazon Elastic Kubernetes Service 中使用 AWS Secrets Manager 秘密 若要將來自 AWS Secrets Manager (ASCP) 的秘密顯示為掛載在 Amazon EKS Pod 中的檔案，您可以使用 AWS Kubernetes Secrets Store CSI Driver 的 Secrets and Configuration Provider。ASCP 可與執行 Amazon EC2 節點群組的 Amazon Elastic Kubernetes Service 1.17\$1 搭配使用。不支援 Amazon EC2 節點群組。 AWS Fargate 透過 ASCP，您可以在 Secrets Manager 中存放和管理您的秘密，然後透過在 Amazon EKS 上執行的工作負載擷取這些秘密。如果您的秘密包含 JSON 格式的多個鍵/值對，您可以選擇要在 Amazon EKS 中掛載的鍵/值對。ASCP 使用 JMESPath 語法來查詢秘密中的鍵值對。ASCP 也可與 Parameter Store 參數搭配使用。ASCP 提供兩種使用 Amazon EKS 進行身分驗證的方法。第一種方法使用服務帳戶的 IAM 角色 (IRSA)。第二種方法使用 Pod 身分識別。每種方法都有其優點和使用案例。 ## 具有服務帳戶 IAM 角色 (IRSA) 的 ASCP 具有服務帳戶 IAM 角色 (IRSA) 的 ASCP 可讓您將來自 的秘密掛載 AWS Secrets Manager 為 Amazon EKS Pod 中的檔案。此方法適用於下列情況： + 您需要將秘密掛載為 Pod 中的檔案。 + 您在 Amazon EC2 節點群組中使用 Amazon EKS 1.17 版或更新版本。 + 您想要從 JSON 格式的秘密擷取特定的鍵/值對。 如需詳細資訊，請參閱[使用 AWS Secrets and Configuration Provider CSI 搭配服務帳戶 (IRSA) 的 IAM 角色](integrating_ascp_irsa.md)。 ## 具有 Pod 身分識別的 ASCP 具有 Pod Identity 的 ASCP 方法可增強安全性，並簡化在 Amazon EKS 中存取秘密的組態。此方法在下列情況下非常有用： + 您需要在 Pod 層級進行更精細的許可管理。 + 您使用 Amazon EKS 1.24 版或更新版本。 + 您想要改善效能與可擴展性。 如需詳細資訊，請參閱[使用 AWS 秘密和組態提供者 CSI 搭配 Amazon EKS 的 Pod 身分](ascp-pod-identity-integration.md)。 ## 選擇正確的方法 決定具有 IRSA 的 ASCP 和具有 Pod 身分識別的 ASCP 時，請考慮下列因素： + Amazon EKSversion：Pod 身分識別需要 Amazon EKS 1.24 版或更高版本，而 CSI 驅動程式可與 Amazon EKS 1.17 版或更高版本搭配使用。 + 安全需求：Pod 身分識別在 Pod 層級提供更精細的控制。 + 效能：Pod 身分識別通常在大規模環境中表現較佳。 + 複雜性：Pod 身分識別透過消除對單獨服務帳戶的需求，簡化設定。 選擇最符合您特定需求與 Amazon EKS 環境的方法。 # 安裝適用於 Amazon EKS 的 ASCP 本節說明如何安裝 Amazon EKS 的 AWS Secrets and Configuration Provider。使用 ASCP，您可以從 Secrets Manager 將秘密掛載，並從 將參數掛載 AWS Systems Manager 為 Amazon EKS Pod 中的檔案。 ## 先決條件 + Amazon EKS 叢集 + 適用於 Pod 身分識別的 1.24 版或更新版本 + 適用於 IRSA 的 1.17 版或更新版本 + AWS CLI 已安裝和設定的 + 已為 Amazon EKS 叢集安裝和設定 kubectl + Helm (3.0 版或更新版本) ## 安裝和設定 ASCP 您可在 [secrets-store-csi-provider-aws](https://github.com/aws/secrets-store-csi-driver-provider-aws) 儲存庫中的 GitHub 取得 ASCP。儲存庫還包含用於建立和掛載秘密的範例 YAML 檔案。 在安裝期間，您可以將 ASCP 設定為使用 FIPS 端點。如需端點清單，請參閱 [AWS Secrets Manager 端點](asm_access.md#endpoints)。 **安裝 ASCP 做為 EKS 附加元件** 1. 安裝 `eksctl`([安裝指示](https://docs.aws.amazon.com/eks/latest/eksctl/installation.html)) 1. 執行下列命令，以[預設組態](https://github.com/aws/secrets-store-csi-driver-provider-aws/blob/main/charts/secrets-store-csi-driver-provider-aws/values.yaml)安裝 附加元件： ``` eksctl create addon --cluster --name aws-secrets-store-csi-driver-provider ``` 如果您想要設定附加元件，請改為執行下列安裝命令： ``` aws eks create-addon --cluster-name --addon-name aws-secrets-store-csi-driver-provider --configuration-values 'file://path/to/config.yaml' ``` 組態檔案可以是 YAML 或 JSON 檔案。若要查看附加元件的組態結構描述： 1. 執行下列命令，並記下 附加元件的最新版本： ``` aws eks describe-addon-versions --addon-name aws-secrets-store-csi-driver-provider ``` 1. 執行下列命令以查看附加元件的組態結構描述，``將 取代為上一個步驟的 版本： ``` aws eks describe-addon-configuration --addon-name aws-secrets-store-csi-driver-provider --addon-version ``` **使用 Helm 安裝 ASCP** 1. 為確認儲存庫指向最新圖表，請使用 `helm repo update.` 1. 安裝圖表。以下是 `helm install`命令的範例： ``` helm install -n kube-system secrets-provider-aws aws-secrets-manager/secrets-store-csi-driver-provider-aws ``` 1. 若要使用 FIPS 端點，請新增下列旗標：`--set useFipsEndpoint=true` 1. 若要設定限流，請新增下列旗標：`--set-json 'k8sThrottlingParams={"qps": "number of queries per second", "burst": "number of queries per second"}'` 1. 如果您的叢集已安裝 Secrets Store CSI 驅動程式，請新增下列旗標：`--set secrets-store-csi-driver.install=false`。這將略過安裝 Secrets Store CSI 驅動程式做為相依性。 **使用儲存庫中的 YAML 進行安裝** + 使用下列命令。 ``` helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts helm install -n kube-system csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver kubectl apply -f https://raw.githubusercontent.com/aws/secrets-store-csi-driver-provider-aws/main/deployment/aws-provider-installer.yaml ``` ## 驗證安裝 若要驗證 EKS 叢集、Secrets Store CSI 驅動程式和 ASCP 外掛程式的安裝，請遵循下列步驟： 1. 驗證 EKS 叢集： ``` eksctl get cluster --name clusterName ``` 此命令應傳回叢集的相關資訊。 1. 驗證 Secrets Store CSI 驅動程式的安裝： ``` kubectl get pods -n kube-system -l app=secrets-store-csi-driver ``` 您應該會看到名稱類似於 `csi-secrets-store-secrets-store-csi-driver-xxx` 的 Pod 正在執行。 1. 驗證 ASCP 外掛程式的安裝： ------ #### [ YAML installation ] ``` $ kubectl get pods -n kube-system -l app=csi-secrets-store-provider-aws ``` 輸出範例： ``` NAME READY STATUS RESTARTS AGE csi-secrets-store-provider-aws-12345 1/1 Running 0 2m ``` ------ #### [ Helm installation ] ``` $ kubectl get pods -n kube-system -l app=secrets-store-csi-driver-provider-aws ``` 輸出範例： ``` NAME READY STATUS RESTARTS AGE secrets-provider-aws-secrets-store-csi-driver-provider-67890 1/1 Running 0 2m ``` ------ 您應該會看到處於 `Running` 狀態的 Pod。 執行這些命令之後，如果一切皆正確設定，您應該會看到所有元件都在執行，而且沒有任何錯誤。如果您遇到任何問題，您可能需要檢查有問題之特定 Pod 的日誌，以進行疑難排解。 ## 疑難排解 1. 若要檢查 ASCP 提供者的日誌，請執行： ``` kubectl logs -n kube-system -l app=csi-secrets-store-provider-aws ``` 1. 檢查`kube-system`命名空間中所有 Pod 的狀態： ``` kubectl -n kube-system get pods ``` ``` kubectl -n kube-system logs pod/PODID ``` 與 CSI 驅動程式和 ASCP 相關的所有 Pod 都應該處於「執行中」狀態。 1. 檢查 CSI 驅動程式版本： ``` kubectl get csidriver secrets-store.csi.k8s.io -o yaml ``` 此命令應傳回已安裝 CSI 驅動程式的相關資訊。 ## 其他資源 如需有關如何搭配 Amazon EKS 使用 ASCP 的詳細資訊，請參閱下列資源： + [搭配 Amazon EKS 使用 Pod 身分識別](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) + [GitHub 上的AWS Secrets Store CSI 驅動程式](https://github.com/aws/secrets-store-csi-driver-provider-aws) # 使用 AWS 秘密和組態提供者 CSI 搭配 Amazon EKS 的 Pod 身分 AWS Secrets and Configuration Provider 與 Pod Identity Agent for Amazon Elastic Kubernetes Service 整合，可為在 Amazon EKS 上執行的應用程式提供增強的安全性、簡化組態並改善效能。從 Secrets Manager 或從 AWS Systems Manager 參數存放區擷取秘密或參數時，Pod Identity 可簡化 Amazon EKS 的 IAM 身分驗證。 Amazon EKS Pod 身分識別透過允許直接透過 Amazon EKS 介面設定許可、減少步驟數量，並消除在 Amazon EKS 和 IAM 服務之間切換的需求，簡化設定 Kubernetes 應用程式 IAM 許可的程序。Pod 身分識別可讓您跨多個叢集使用單一 IAM 角色，而無需更新信任政策，並支援[角色工作階段標籤](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-abac.html#pod-id-abac-tags)，以實現更精細的存取控制。這種方法不僅允許跨角色重複使用許可政策來簡化政策管理，還允許根據相符標籤存取 AWS 資源來增強安全性。 ## 運作方式 1. Pod 身分識別可將 IAM 角色指派給 Pod。 1. ASCP 使用此角色進行身分驗證 AWS 服務。 1. 如果獲得授權，ASCP 會擷取請求的秘密，並將其提供給 Pod。 如需詳細資訊，請參閱《Amazon EKS 使用者指南》**中的[了解 Amazon EKS Pod 身分識別的運作方式](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-how-it-works.html)。 ## 先決條件 **重要** 僅雲端中的 Amazon EKS 支援 Pod 身分識別。Amazon EC2 執行個體上的 [Amazon EKS Anywhere](https://aws.amazon.com/eks/eks-anywhere/)、[Red Hat OpenShift Service on AWS](https://aws.amazon.com/rosa/) 或自我管理型 Kubernetes 叢集不支援此功能。 + Amazon EKS 叢集 (1.24 版或更新版本) + 透過 存取 AWS CLI 和 Amazon EKS 叢集 `kubectl` + 存取兩個 AWS 帳戶 （用於跨帳戶存取） ## 安裝 Amazon EKS Pod 身分識別代理程式 若要將 Pod 身分識別與叢集搭配使用，您必須安裝 Amazon EKS Pod 身分識別代理程式附加元件。 **安裝 Pod 身分識別代理程式** + 在叢集上安裝 Pod Identity Agent 附加元件： ``` eksctl create addon \ --name eks-pod-identity-agent \ --cluster clusterName \ --region region ``` ## 使用 Pod 身分識別設定 ASCP 1. 建立許可政策，以授予 Pod 需要存取之秘密的 `secretsmanager:GetSecretValue`和 `secretsmanager:DescribeSecret`許可。如需政策範例，請參閱 [範例：讀取和描述個別秘密的許可](auth-and-access_iam-policies.md#auth-and-access_examples-read-and-describe)。 1. 建立由 Amazon EKS 服務主體擔任的 IAM 角色，用於 Pod 身分識別： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "pods.eks.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession" ] } ] } ``` ------ 將 IAM 政策連接至角色： ``` aws iam attach-role-policy \ --role-name MY_ROLE \ --policy-arn POLICY_ARN ``` 1. 建立 Pod 身分識別關聯。如需範例，請參閱《Amazon EKS 使用者指南》**中的[建立 Pod 身分識別關聯](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-association.html#pod-id-association-create) 1. 建立 `SecretProviderClass`，指定要掛載在 Pod 中的秘密： ``` kubectl apply -f https://raw.githubusercontent.com/aws/secrets-store-csi-driver-provider-aws/main/examples/ExampleSecretProviderClass-PodIdentity.yaml ``` 在 IRSA 和 Pod 身分識別之間，`SecretProviderClass` 主要差異是選用參數 `usePodIdentity`。這是可決定身分驗證方法的選用欄位。未指定時，它會預設為使用服務帳戶的 IAM 角色 (IRSA)。 + 若要使用 EKS Pod 身分識別，請使用下列任何值：`"true", "True", "TRUE", "t", "T"`。 + 若要明確使用 IRSA，請設定為下列任何值：`"false", "False", "FALSE", "f", or "F"`。 1. 在 下部署掛載秘密的 Pod`/mnt/secrets-store`： ``` kubectl apply -f https://raw.githubusercontent.com/aws/secrets-store-csi-driver-provider-aws/main/examples/ExampleDeployment-PodIdentity.yaml ``` 1. 如果您使用私有 Amazon EKS 叢集，請確定叢集所在的 VPC 具有 AWS STS 端點。如需有關建立端點的資訊，請參閱 *AWS Identity and Access Management User Guide* 中的 [Interface VPC endpoints](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_interface_vpc_endpoints.html)。 ### 驗證秘密掛載 若要驗證秘密是否已正確掛載，請執行下列命令： ``` kubectl exec -it $(kubectl get pods | awk '/pod-identity-deployment/{print $1}' | head -1) -- cat /mnt/secrets-store/MySecret ``` **設定 Amazon EKS Pod Identity 以存取 Secrets Manager 中的秘密** 1. 建立許可政策，以授予 Pod 需要存取之秘密的 `secretsmanager:GetSecretValue`和 `secretsmanager:DescribeSecret`許可。如需政策範例，請參閱 [範例：讀取和描述個別秘密的許可](auth-and-access_iam-policies.md#auth-and-access_examples-read-and-describe)。 1. 如果您還沒有秘密，請在 Secrets Manager 中建立秘密。 ## 疑難排解 您可以透過描述 Pod 部署來檢視大多數錯誤。 **若要查看容器的錯誤訊息** 1. 使用下列命令取得 Pod 名稱清單。如果不使用預設命名空間，請使用 `-n NAMESPACE`。 ``` kubectl get pods ``` 1. 若要描述 Pod，請在下列命令中，針對 *PODID* 使用您在上一個步驟中找到的 Pod 中的 Pod ID。如果不使用預設命名空間，請使用 `-n NAMESPACE`。 ``` kubectl describe pod/PODID ``` **若要查看 ASCP 的錯誤** + 若要在提供者日誌中尋找更多資訊，請在下列命令中，針對 *PODID* 使用 *csi-secrets-store-provider-aws* Pod 的 ID。 ``` kubectl -n kube-system get pods kubectl -n kube-system logs pod/PODID ``` # 使用 AWS Secrets and Configuration Provider CSI 搭配服務帳戶 (IRSA) 的 IAM 角色 **Topics** + [先決條件](#prerequisites) + [設定存取控制](#integrating_ascp_irsa_access) + [識別要掛載的機密](#integrating_ascp_irsa_mount) + [疑難排解](#integrating_ascp_irsa_trouble) ## 先決條件 + Amazon EKS 叢集 (1.17 版或更新版本) + 透過 存取 AWS CLI 和 Amazon EKS 叢集 `kubectl` ## 設定存取控制 ASCP 會擷取 Amazon EKS Pod 身分識別，並將其交換為 IAM 角色。您可以在 IAM 政策中為該 IAM 角色設定許可。當 ASCP 擔任 IAM 角色時，它會存取您授權的秘密。除非您也將其與 IAM 角色建立關聯，否則其他容器無法存取秘密。 **授予 Amazon EKS Pod 存取 Secrets Manager 中的秘密的權限** 1. 建立許可政策，將 Pod 需要存取的秘密授予 `secretsmanager:GetSecretValue`和 `secretsmanager:DescribeSecret`許可。如需政策範例，請參閱 [範例：讀取和描述個別秘密的許可](auth-and-access_iam-policies.md#auth-and-access_examples-read-and-describe)。 1. 如果尚未建立，請為叢集建立 IAM OpenID Connect (OIDC) 提供者。如需詳細資訊，請參閱《Amazon EKS 使用者指南》**中的[為您的叢集建立 IAM OIDC 身分提供者](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html)。 1. 建立[服務帳戶的 IAM 角色](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)，並將政策連接至該角色。如需詳細資訊，請參閱《Amazon EKS 使用者指南》**中的[建立服務帳戶的 IAM 角色](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)。 1. 如果您使用私有 Amazon EKS 叢集，請確定叢集所在的 VPC 具有 AWS STS 端點。如需有關建立端點的資訊，請參閱 *AWS Identity and Access Management User Guide* 中的 [Interface VPC endpoints](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_interface_vpc_endpoints.html)。 ## 識別要掛載的機密 若要確定 ASCP 在 Amazon EKS 中掛載哪些機密作為檔案系統上的檔案，請建立 [SecretProviderClass](ascp-examples.md#ascp-examples-secretproviderclass) YAML 檔案。`SecretProviderClass` 列出要掛載的秘密和要掛載的檔案名稱。`SecretProviderClass` 必須與其參考的 Amazon EKS Pod 位於同一命名空間。 ### 將秘密掛載為檔案 下列指示說明如何使用範例 YAML 檔案 [ExampleSecretProviderClass.yaml](https://github.com/aws/secrets-store-csi-driver-provider-aws/blob/main/examples/ExampleSecretProviderClass-IRSA.yaml) 和 [ExampleDeployment.yaml](https://github.com/aws/secrets-store-csi-driver-provider-aws/blob/main/examples/ExampleDeployment-IRSA.yaml) 將秘密掛載為檔案。 **在 Amazon EKS 中掛載秘密** 1. 將 `SecretProviderClass` 套用至 Pod： ``` kubectl apply -f ExampleSecretProviderClass.yaml ``` 1. 部署您的 Pod： ``` kubectl apply -f ExampleDeployment.yaml ``` 1. ASCP 可掛載檔案。 ## 疑難排解 您可以透過描述 Pod 部署來檢視大多數錯誤。 **若要查看容器的錯誤訊息** 1. 使用下列命令取得 Pod 名稱清單。如果不使用預設命名空間，請使用 `-n nameSpace`。 ``` kubectl get pods ``` 1. 若要描述 Pod，請在下列命令中，針對 *podId* 使用您在上一個步驟中找到的 Pod 中的 Pod ID。如果不使用預設命名空間，請使用 `-n nameSpace`。 ``` kubectl describe pod/podId ``` **若要查看 ASCP 的錯誤** + 若要在提供者日誌中尋找詳細資訊，請在下列命令中，針對 *podId* 使用 *csi-secrets-store-provider-aws* Pod 的 ID。 ``` kubectl -n kube-system get pods kubectl -n kube-system logs Pod/podId ``` + **驗證是否已安裝 `SecretProviderClass` CRD：** ``` kubectl get crd secretproviderclasses.secrets-store.csi.x-k8s.io ``` 此命令應會傳回有關 `SecretProviderClass` 自訂資源定義的資訊。 + **驗證是否已建立 SecretProviderClass 物件。** ``` kubectl get secretproviderclass SecretProviderClassName -o yaml ``` # AWS 秘密和組態提供者程式碼範例 ## ASCP 身分驗證與存取控制範例 ### 範例：允許 Amazon EKS Pod 身分識別服務 (pods.eks.amazonaws.com) 擔任角色與標記工作階段的 IAM 政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "pods.eks.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession" ] } ] } ``` ------ ## SecretProviderClass 您可以使用 YAML 來描述要使用 ASCP 在 Amazon EKS 中裝載的機密。如需範例，請參閱 [SecretProviderClass 用量](#ascp-scenarios-secretproviderclass)。 ### SecretProviderClass YAML 結構 ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: name spec: provider: aws parameters: region: failoverRegion: pathTranslation: usePodIdentity: preferredAddressType: objects: ``` 參數欄位包含掛載請求的詳細資訊： **region** （選用） 秘密 AWS 區域 的 。如果不使用此欄位，ASCP 會從節點上的註釋尋找區域。此查閱會增加掛載請求的額外負荷，因此建議您為使用大量 Pod 的叢集提供區域。 如果您也指定 `failoverRegion`，則 ASCP 會嘗試從這兩個區域擷取機密。如果任一區域傳回 4xx 錯誤 (例如身分驗證問題)，則 ASCP 不會掛載任一機密。如果已成功從 `region` 擷取機密，則 ASCP 會掛載該機密值。如果未成功從 `region` 擷取機密，但已成功從 `failoverRegion` 擷取機密，則 ASCP 會掛載該機密值。 **failoverRegion** (選用) 如果您包含此欄位，則 ASCP 會嘗試從 `region` 中定義的區域和此欄位擷取機密。如果任一區域傳回 4xx 錯誤 (例如身分驗證問題)，則 ASCP 不會掛載任一機密。如果已成功從 `region` 擷取機密，則 ASCP 會掛載該機密值。如果未成功從 `region` 擷取機密，但已成功從 `failoverRegion` 擷取機密，則 ASCP 會掛載該機密值。如需如何使用此欄位的範例，請參閱 [多區域秘密容錯移轉](#multi-region-failover)。 **pathTranslation** (選用) 如果 Amazon EKS 中的檔案名稱將包含路徑分隔符號字元，例如 Linux 上的斜線 (/)，則要使用的單一替代字元。ASCP 無法建立包含路徑分隔符號字元的掛載檔案。相反地，ASCP 會將路徑分隔符號字元取代為其他字元。如果不使用此欄位，則取代字元為底線 (\$1)，例如 `My/Path/Secret` 掛載為 `My_Path_Secret`。 若要避免發生字元取代的情況，請輸入字串 `False`。 **usePodIdentity** (選用) 決定身分驗證方法。未指定時，它預設為服務帳戶 (IRSA) 的 IAM 角色。 + 若要使用 EKS Pod 身分識別，請使用下列任何值：`"true"`、`"True"`、`"TRUE"`、`"t"` 或 `"T"`。 + 若要明確使用 IRSA，請設定下列任何值：`"false"`、`"False"`、`"f"`、`"FALSE"` 或 `"F"`。 **preferredAddressType** (選用) 指定 Pod 身分識別代理程式端點通訊的偏好 IP 位址類型。此欄位僅在使用 EKS Pod 身分識別功能時適用，並在使用服務帳戶的 IAM 角色時忽略。值不區分大小寫。有效的值如下： + `"ipv4"`、`"IPv4"` 或 `"IPV4"` – 強制使用 Pod 身分識別代理程式 IPv4 端點 + `"ipv6"`、`"IPv6"` 或 `"IPV6"` – 強制使用 Pod 身分識別代理程式 IPv6 端點 + 未指定 – 使用自動端點選擇、先嘗試 IPv4 端點，並在 IPv4 失敗時退回到 IPv6 端點 **objects** 包含待掛載秘密的 YAML 宣告的字串。建議使用 YAML 多行字串或分隔號 (\$1) 字元。 **objectName** 必要. 指定要擷取的秘密或參數名稱。對於 Secrets Manager，這是 [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html#API_GetSecretValue_RequestParameters](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html#API_GetSecretValue_RequestParameters) 參數，並且可以是秘密的易記名稱或完整 ARN。對於 SSM 參數存放區，這是 參數[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html#API_GetParameter_RequestParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html#API_GetParameter_RequestParameters)的 ，可以是 參數的名稱或完整 ARN。 **objectType** 如果未針對 `objectName` 使用 Secrets Manager ARN，其則為必要欄位。可以是 `secretsmanager` 或 `ssmparameter`。 **objectAlias** (選用) Amazon EKS Pod 中秘密的檔案名稱。如果您未指定此欄位，`objectName` 會顯示為檔案名稱。 **filePermission** （選用） 指定用來掛載秘密的檔案許可的 4 位數八進位字串。如果您未指定此欄位，則會預設為 `"0644"`。 **objectVersion** (選用) 秘密的版本 ID。不建議，因為每次更新機密時都必須更新版本 ID。依預設，會使用最新版本。如果您包含 `failoverRegion`，則此欄位代表主要 `objectVersion`。 **objectVersionLabel** (選用) 版本的別名。預設值為最新版本的 AWSCURRENT。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。如果您包含 `failoverRegion`，則此欄位代表主要 `objectVersionLabel`。 **jmesPath** (選用) 要掛載在 Amazon EKS 中之檔案的秘密金鑰映射。若要使用此欄位，您的秘密值必須是 JSON 格式。如果使用此欄位，您必須包含 `path` 和 `objectAlias`。 **路徑** 來自秘密值 JSON 中金鑰/值對的金鑰。如果欄位包含連字號，請使用單引號將其逸出，例如：`path: '"hyphenated-path"'`。 **objectAlias** 要掛載在 Amazon EKS Pod 中的檔案名稱。如果欄位包含連字號，請使用單引號將其逸出，例如：`objectAlias: '"hyphenated-alias"'`。 **filePermission** （選用） 指定用來掛載秘密的檔案許可的 4 位數八進位字串。如果您未指定此欄位，則會預設為父物件的檔案許可。 **failoverObject** (選用) 如果您指定此欄位，則 ASCP 會嘗試擷取在主要 `objectName` 中指定的機密和在 `failoverObject` `objectName` 子欄位中指定的機密。如果任一項傳回 4xx 錯誤 (例如身分驗證問題)，則 ASCP 不會掛載任一機密。如果已成功從主要 `objectName` 擷取機密，則 ASCP 會掛載該機密值。如果未成功從主要 `objectName` 擷取機密，但已成功從容錯移轉 `objectName` 擷取機密，則 ASCP 會掛載該機密值。如果包含此欄位，則您必須包含欄位 `objectAlias`。如需如何使用此欄位的範例，請參閱 [容錯移轉至不同的秘密](#failover-secret)。 當容錯移轉機密不是複本時，您通常會使用此欄位。如需如何指定複本的範例，請參閱 [多區域秘密容錯移轉](#multi-region-failover)。 **objectName** 容錯移轉機密的名稱或完整 ARN。如果您使用 ARN，則 ARN 中的區域必須與欄位 `failoverRegion` 相符。 **objectVersion** (選用) 秘密的版本 ID。必須與主要 `objectVersion` 相符。不建議，因為每次更新機密時都必須更新版本 ID。依預設，會使用最新版本。 **objectVersionLabel** (選用) 版本的別名。預設值為最新版本的 AWSCURRENT。如需詳細資訊，請參閱[秘密版本](whats-in-a-secret.md#term_version)。 ### 建立基本 SecretProviderClass 組態，以在 Amazon EKS Pod 中掛載秘密。 ------ #### [ Pod Identity ] SecretProviderClass 可在相同的 Amazon EKS 叢集中使用秘密： ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aws-secrets-manager spec: provider: aws parameters: objects: | - objectName: "mySecret" objectType: "secretsmanager" usePodIdentity: "true" ``` ------ #### [ IRSA ] ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: deployment-aws-secrets spec: provider: aws parameters: objects: | - objectName: "MySecret" objectType: "secretsmanager" ``` ------ ### SecretProviderClass 用量 使用這些範例為不同的案例建立 SecretProviderClass 組態。 #### 範例：依名稱或 ARN 掛載機密 此範例說明如何掛載三種不同類型的秘密： + 完整 ARN 指定的秘密 + 名稱指定的秘密 + 秘密的特定版本 ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aws-secrets spec: provider: aws parameters: objects: | - objectName: "arn:aws:secretsmanager:us-east-2:777788889999:secret:MySecret2-d4e5f6" - objectName: "MySecret3" objectType: "secretsmanager" - objectName: "MySecret4" objectType: "secretsmanager" objectVersionLabel: "AWSCURRENT" ``` #### 範例：從秘密掛載金鑰/值對 此範例示範如何從 JSON 格式的秘密掛載特定的鍵/值對： ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aws-secrets spec: provider: aws parameters: objects: | - objectName: "arn:aws:secretsmanager:us-east-2:777788889999:secret:MySecret-a1b2c3" jmesPath: - path: username objectAlias: dbusername - path: password objectAlias: dbpassword ``` #### 範例：依檔案許可掛載秘密 此範例示範如何使用特定檔案許可掛載秘密 ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aws-secrets spec: provider: aws parameters: objects: | - objectName: "mySecret" objectType: "secretsmanager" filePermission: "0600" jmesPath: - path: username objectAlias: dbusername filePermission: "0400" ``` #### 範例：容錯移轉組態範例 這些範例示範如何設定秘密的容錯移轉。 ##### 多區域秘密容錯移轉 此範例說明如何為跨多個區域複寫的秘密設定自動容錯移轉： ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aws-secrets spec: provider: aws parameters: region: us-east-1 failoverRegion: us-east-2 objects: | - objectName: "MySecret" ``` ##### 容錯移轉至不同的秘密 此範例示範如何設定容錯移轉至不同的秘密 （非複本）： ``` apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aws-secrets spec: provider: aws parameters: region: us-east-1 failoverRegion: us-east-2 objects: | - objectName: "arn:aws:secretsmanager:us-east-1:777788889999:secret:MySecret-a1b2c3" objectAlias: "MyMountedSecret" failoverObject: - objectName: "arn:aws:secretsmanager:us-east-2:777788889999:secret:MyFailoverSecret-d4e5f6" ``` ## 其他資源 如需有關如何搭配 Amazon EKS 使用 ASCP 的詳細資訊，請參閱下列資源： + [搭配 Amazon EKS 使用 Pod 身分識別](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) + [使用 AWS 秘密和組態提供者](https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_ascp_csi.html) + [GitHub 上的AWS Secrets Store CSI 驅動程式](https://github.com/aws/secrets-store-csi-driver-provider-aws) # 在 AWS Lambda 函數中使用 AWS Secrets Manager 秘密 AWS Lambda 是一種無伺服器運算服務，可讓您執行程式碼，而無需佈建或管理伺服器。參數存放區是 的一項功能 AWS Systems Manager，可為組態資料管理和秘密管理提供安全的階層式儲存。您可以使用 AWS Parameters and Secrets Lambda Extension 來擷取和快取 Lambda 函數中的 AWS Secrets Manager 秘密和參數存放區參數，而無需使用 SDK。如需使用此延伸模組的詳細資訊，請參閱[《Lambda 開發人員指南》中的在 Lambda 函數中使用 Secrets Manager 秘密](https://docs.aws.amazon.com/lambda/latest/dg/with-secrets-manager.html)。 ** ## 搭配 Lambda 使用 Secrets Manager 秘密 Lambda 開發人員指南提供在 Lambda 函數中使用 Secrets Manager 秘密的完整說明。開始使用： 1. 遵循 [Lambda 函數中的使用 Secrets Manager 秘密](https://docs.aws.amazon.com/lambda/latest/dg/with-secrets-manager.html)step-by-step教學課程，其中包括： + 使用您偏好的執行時間建立 Lambda 函數 (Python、Node.js、Java) + 新增 AWS 參數和秘密 Lambda 延伸做為 layer + 設定必要的許可 + 撰寫程式碼以從延伸模組擷取秘密 + 測試您的 函數 1. 了解用於設定延伸模組行為的環境變數，包括快取設定和逾時 1. 了解使用秘密輪換的最佳實務 ### 在 VPC 中使用 Secrets Manager 和 Lambda 如果您的 Lambda 函數在 VPC 中執行，您需要建立 VPC 端點，以便延伸模組可以呼叫 Secrets Manager。如需詳細資訊，請參閱[使用 AWS Secrets Manager VPC 端點](vpc-endpoint-overview.md)。 ## 使用 AWS 參數和秘密 Lambda 延伸模組 延伸模組可以擷取 Secrets Manager 秘密和 Parameter Store 參數。如需搭配 延伸模組使用參數存放區參數的詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[在 Lambda 函數中使用參數存放區參數](https://docs.aws.amazon.com/systems-manager/latest/userguide/ps-integration-lambda-extensions.html)。 Systems Manager 文件包括： + 延伸模組如何與參數存放區搭配使用的詳細解釋 + 將擴充功能新增至 Lambda 函數的指示 + 用於設定延伸模組的環境變數 + 用於擷取參數的範例命令 + 所有支援的架構和區域的完整延伸 ARNs 清單 # 使用 AWS Secrets Manager 代理程式 ## Secrets Manager 代理程式的運作方式 AWS Secrets Manager 代理程式是一種用戶端 HTTP 服務，可協助您標準化在運算環境中從 Secrets Manager 取用秘密的方式。您可以搭配下列服務使用： + AWS Lambda + Amazon Elastic Container Service + Amazon Elastic Kubernetes Service + Amazon Elastic Compute Cloud Secrets Manager 代理程式會擷取和快取記憶體中的秘密，讓您的應用程式從 localhost 取得秘密，而不是直接呼叫 Secrets Manager。Secrets Manager Agent 只能讀取秘密，無法修改秘密。 **重要** Secrets Manager 代理程式會使用您環境中的 AWS 登入資料來呼叫 Secrets Manager。它包含對伺服器端請求偽造 (SSRF) 的保護，以協助改善秘密安全性。Secrets Manager 代理程式預設使用後量子 ML-KEM 金鑰交換作為最高優先順序金鑰交換。 ## 了解 Secrets Manager 代理程式快取 Secrets Manager 代理程式使用記憶體內快取，會在 Secrets Manager 代理程式重新啟動時重設。它會根據下列項目定期重新整理快取的秘密值： + 預設重新整理頻率 (TTL) 為 300 秒 + 您可以使用組態檔案修改 TTL + 當您在 TTL 過期後請求秘密時，會發生重新整理 **注意** Secrets Manager 代理程式不包含快取失效。如果秘密在快取項目過期之前輪換，Secrets Manager Agent 可能會傳回過時的秘密值。 Secrets Manager Agent 會以與 回應相同的格式傳回秘密值`GetSecretValue`。不會在快取中加密秘密值。 **Topics** + [Secrets Manager 代理程式的運作方式](#agent-overview) + [了解 Secrets Manager 代理程式快取](#agent-caching) + [建置 Secrets Manager 代理程式](#secrets-manager-agent-build) + [安裝 Secrets Manager 代理程式](#secrets-manager-agent-install) + [使用 Secrets Manager Agent 擷取秘密](#secrets-manager-agent-call) + [了解 `refreshNow` 參數](#secrets-manager-agent-refresh) + [設定 Secrets Manager 代理程式](#secrets-manager-agent-config) + [選用功能](#secrets-manager-agent-features) + [日誌](#secrets-manager-agent-log) + [安全考量](#secrets-manager-agent-security) ## 建置 Secrets Manager 代理程式 開始之前，請確定您已為平台安裝標準開發工具和 Rust 工具。 **注意** 在 macOS 上建立已啟用 `fips`功能的代理程式，目前需要以下解決方法： 建立名為 的環境變數`SDKROOT`，其設定為執行的結果 `xcrun --show-sdk-path` ------ #### [ RPM-based systems ] **在以 RPM 為基礎的系統上建置** 1. 使用 儲存庫中提供的`install`指令碼。 指令碼會在啟動時產生隨機 SSRF 字符，並將其存放在 檔案 中`/var/run/awssmatoken`。安裝指令碼建立的 `awssmatokenreader` 群組可讀取權杖。 1. 若要允許應用程式讀取權杖檔案，您需要將應用程式執行所在的使用者帳戶新增至 `awssmatokenreader`群組。例如，您可以使用下列 usermod 命令授予應用程式讀取權杖檔案的許可，其中 ** 是應用程式執行所在的使用者 ID。 ``` sudo usermod -aG awssmatokenreader ``` **安裝開發工具** 在 AL2023 等以 RPM 為基礎的系統上，安裝 開發工具 群組： ``` sudo yum -y groupinstall "Development Tools" ``` 1. **安裝 Rust** 請遵循 [Rust 文件中的安裝](https://www.rust-lang.org/tools/install) *Rust* 說明： ``` curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions . "$HOME/.cargo/env" ``` 1. **建置代理程式** 使用貨物建置命令建置 Secrets Manager 代理程式： ``` cargo build --release ``` 您可以在 下找到可執行檔`target/release/aws_secretsmanager_agent`。 ------ #### [ Debian-based systems ] **在 Debian 型系統上建置** 1. **安裝開發工具** 在 Ubuntu 等 Debian 系統上，安裝 build-essential 套件： ``` sudo apt install build-essential ``` 1. **安裝 Rust** 請遵循 [Rust 文件中的安裝](https://www.rust-lang.org/tools/install) *Rust* 說明： ``` curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions . "$HOME/.cargo/env" ``` 1. **建置代理程式** 使用貨物建置命令建置 Secrets Manager 代理程式： ``` cargo build --release ``` 您可以在 下找到可執行檔`target/release/aws_secretsmanager_agent`。 ------ #### [ Windows ] **在 Windows 上建置** 1. **設定開發環境** 遵循 *Microsoft* [Windows 文件中在 Windows for Rust 上設定開發環境](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup)的指示。 1. **建置代理程式** 使用貨物建置命令建置 Secrets Manager 代理程式： ``` cargo build --release ``` 您可以在 下找到可執行檔`target/release/aws_secretsmanager_agent.exe`。 ------ #### [ Cross-compile natively ] **以原生方式跨編譯** 1. **安裝跨編譯工具** 在提供 mingw-w64 套件的分佈上，例如 Ubuntu，安裝跨編譯工具鏈： ``` # Install the cross compile tool chain sudo add-apt-repository universe sudo apt install -y mingw-w64 ``` 1. **新增 Rust 建置目標** 安裝 Windows GNU 建置目標： ``` rustup target add x86_64-pc-windows-gnu ``` 1. **適用於 Windows 的建置** 跨編譯適用於 Windows 的代理程式： ``` cargo build --release --target x86_64-pc-windows-gnu ``` 您可以在 找到可執行檔`target/x86_64-pc-windows-gnu/release/aws_secretsmanager_agent.exe`。 ------ #### [ Cross compile with Rust cross ] **使用 Rust cross 進行交叉編譯** 如果系統無法原生使用跨編譯工具，您可以使用 Rust 跨專案。如需詳細資訊，請參閱 https：//[https://github.com/cross-rs/cross](https://github.com/cross-rs/cross)。 **重要** 我們建議在建置環境中使用 32GB 的磁碟空間。 1. **設定 Docker** 安裝和設定 Docker： ``` # Install and start docker sudo yum -y install docker sudo systemctl start docker sudo systemctl enable docker # Make docker start after reboot ``` 1. **設定 Docker 許可** 將您的使用者新增至 Docker 群組： ``` # Give ourselves permission to run the docker images without sudo sudo usermod -aG docker $USER newgrp docker ``` 1. **適用於 Windows 的建置** 安裝 Cross 並建置可執行檔： ``` # Install cross and cross compile the executable cargo install cross cross build --release --target x86_64-pc-windows-gnu ``` ------ ## 安裝 Secrets Manager 代理程式 從下列安裝選項中選擇您的運算環境。 ------ #### [ Amazon EC2 ] **在 Amazon EC2 上安裝 Secrets Manager 代理程式** 1. **導覽至組態目錄** 變更為組態目錄： ``` cd aws_secretsmanager_agent/configuration ``` 1. **執行安裝指令碼** 執行 儲存庫中提供的`install`指令碼。 指令碼會在啟動時產生隨機 SSRF 字符，並將其存放在 檔案 中`/var/run/awssmatoken`。安裝指令碼建立的 `awssmatokenreader` 群組可讀取權杖。 1. **設定應用程式許可** 將應用程式執行所在的使用者帳戶新增至 `awssmatokenreader`群組： ``` sudo usermod -aG awssmatokenreader APP_USER ``` 以應用程式執行所在的使用者 ID 取代 *APP\$1USER*。 ------ #### [ Container Sidecar ] 您可以使用 Docker 將 Secrets Manager Agent 作為附屬容器與應用程式一起執行。然後，您的應用程式可以從 Secrets Manager Agent 提供的本機 HTTP 伺服器擷取秘密。如需 Docker 的相關資訊，請參閱 [Docker 文件](https://docs.docker.com)。 **為 Secrets Manager Agent 建立附屬容器** 1. **建立代理程式 Dockerfile** 為 Secrets Manager Agent 附屬容器建立 Dockerfile： ``` # Use the latest Debian image as the base FROM debian:latest # Set the working directory inside the container WORKDIR /app # Copy the Secrets Manager Agent binary to the container COPY secrets-manager-agent . # Install any necessary dependencies RUN apt-get update && apt-get install -y ca-certificates # Set the entry point to run the Secrets Manager Agent binary ENTRYPOINT ["./secrets-manager-agent"] ``` 1. **建立應用程式 Dockerfile** 為您的用戶端應用程式建立 Dockerfile。 1. **建立 Docker Compose 檔案** 建立 Docker Compose 檔案，以使用共用網路介面執行兩個容器： **重要** 您必須載入 AWS 登入資料和 SSRF 字符，應用程式才能使用 Secrets Manager Agent。如需 Amazon EKS 和 Amazon ECS，請參閱下列內容： 《*Amazon EKS 使用者指南*》中的[管理存取權](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html) 《[Amazon ECS 開發人員指南》中的 Amazon ECS 任務 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) ** ``` version: '3' services: client-application: container_name: client-application build: context: . dockerfile: Dockerfile.client command: tail -f /dev/null # Keep the container running secrets-manager-agent: container_name: secrets-manager-agent build: context: . dockerfile: Dockerfile.agent network_mode: "container:client-application" # Attach to the client-application container's network depends_on: - client-application ``` 1. **複製代理程式二進位** 將`secrets-manager-agent`二進位檔複製到包含 Dockerfiles 和 Docker Compose 檔案的相同目錄。 1. **建置和執行容器** 使用 Docker Compose 建置和執行容器： ``` docker-compose up --build ``` 1. **後續步驟** 您現在可以使用 Secrets Manager Agent 從用戶端容器擷取秘密。如需詳細資訊，請參閱[使用 Secrets Manager Agent 擷取秘密](#secrets-manager-agent-call)。 ------ #### [ Lambda ] 您可以將 [Secrets Manager 代理程式封裝為 Lambda 延伸](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html)模組。然後，您可以將[它做為 layer 新增至 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html)，並從 Lambda 函數呼叫 Secrets Manager Agent 以取得秘密。 下列指示說明如何使用 [https://github.com/aws/aws-secretsmanager-agent](https://github.com/aws/aws-secretsmanager-agent)：// `secrets-manager-agent-extension.sh`中的範例指令碼來安裝 Secrets Manager Agent 做為 Lambda 延伸模組，以取得名為 *MyTest* 的秘密。 **為 Secrets Manager Agent 建立 Lambda 擴充功能** 1. **封裝代理程式層** 從 Secrets Manager Agent 程式碼套件的根目錄，執行下列命令： ``` AWS_ACCOUNT_ID=AWS_ACCOUNT_ID LAMBDA_ARN=LAMBDA_ARN # Build the release binary cargo build --release --target=x86_64-unknown-linux-gnu # Copy the release binary into the `bin` folder mkdir -p ./bin cp ./target/x86_64-unknown-linux-gnu/release/aws_secretsmanager_agent ./bin/secrets-manager-agent # Copy the `secrets-manager-agent-extension.sh` example script into the `extensions` folder. mkdir -p ./extensions cp aws_secretsmanager_agent/examples/example-lambda-extension/secrets-manager-agent-extension.sh ./extensions # Zip the extension shell script and the binary zip secrets-manager-agent-extension.zip bin/* extensions/* # Publish the layer version LAYER_VERSION_ARN=$(aws lambda publish-layer-version \ --layer-name secrets-manager-agent-extension \ --zip-file "fileb://secrets-manager-agent-extension.zip" | jq -r '.LayerVersionArn') ``` 1. **設定 SSRF 字符** 代理程式的預設組態會自動將 SSRF 字符設定為預設`AWS_SESSION_TOKEN`或`AWS_CONTAINER_AUTHORIZATION_TOKEN`環境變數中設定的值 （啟用 SnapStart 的 Lambda 函數的後一個變數）。或者，您可以使用 Lambda 函數的任意值來定義`AWS_TOKEN`環境變數，因為此變數優先於其他兩個變數。如果您選擇使用 `AWS_TOKEN`環境變數，則必須使用 `lambda:UpdateFunctionConfiguration`呼叫來設定該環境變數。 1. **將 layer 連接至函數** 將 layer 版本連接至 Lambda 函數： ``` # Attach the layer version to the Lambda function aws lambda update-function-configuration \ --function-name $LAMBDA_ARN \ --layers "$LAYER_VERSION_ARN" ``` 1. **更新函數程式碼** 更新您的 Lambda 函數，以查詢`http://localhost:2773/secretsmanager/get?secretId=MyTest``X-Aws-codes-Secrets-Token`標頭值設定為從上述環境變數取得的 SSRF 字符值，以擷取秘密。請務必在應用程式程式碼中實作重試邏輯，以因應 Lambda 延伸模組的初始化和註冊延遲。 1. **測試函數** 叫用 Lambda 函數來驗證是否正確擷取秘密。 ------ ## 使用 Secrets Manager Agent 擷取秘密 若要擷取秘密，請使用秘密名稱或 ARN 做為查詢參數來呼叫本機 Secrets Manager Agent 端點。根據預設，Secrets Manager Agent 會擷取秘密的`AWSCURRENT`版本。若要擷取不同的版本，請使用 versionStage 或 versionId 參數。 **重要** 為了協助保護 Secrets Manager Agent，您必須在每個請求中包含 SSRF 字符標頭：`X-Aws-Parameters-Secrets-Token`。Secrets Manager 代理程式拒絕沒有此標頭或具有無效 SSRF 字符的請求。您可以在 中自訂 SSRF 標頭名稱[設定 Secrets Manager 代理程式](#secrets-manager-agent-config)。 ### 所需的許可 Secrets Manager 代理程式使用適用於 Rust 的 AWS SDK，它使用[AWS 登入資料提供者鏈結](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。這些 IAM 登入資料的身分決定 Secrets Manager Agent 擷取秘密的許可。 + `secretsmanager:DescribeSecret` + `secretsmanager:GetSecretValue` 如需許可的詳細資訊，請參閱「[的許可參考 AWS Secrets Manager](auth-and-access.md#reference_iam-permissions)」。 **重要** 將秘密值提取至 Secrets Manager Agent 後，任何可存取運算環境和 SSRF 字符的使用者都可以從 Secrets Manager Agent 快取存取秘密。如需詳細資訊，請參閱[安全考量](#secrets-manager-agent-security)。 ### 範例請求 ------ #### [ curl ] **Example 範例 – 使用 curl 取得秘密** 下列 curl 範例示範如何從 Secrets Manager Agent 取得秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。 ``` curl -v -H \\ "X-Aws-Parameters-Secrets-Token: $(/var/run/awssmatoken)" \\ 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID' \\ echo ``` ------ #### [ Python ] **Example 範例 – 使用 Python 取得秘密** 下列 Python 範例示範如何從 Secrets Manager Agent 取得秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。 ``` import requests import json # Function that fetches the secret from Secrets Manager Agent for the provided secret id. def get_secret(): # Construct the URL for the GET request url = f"http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID" # Get the SSRF token from the token file with open('/var/run/awssmatoken') as fp: token = fp.read() headers = { "X-Aws-Parameters-Secrets-Token": token.strip() } try: # Send the GET request with headers response = requests.get(url, headers=headers) # Check if the request was successful if response.status_code == 200: # Return the secret value return response.text else: # Handle error cases raise Exception(f"Status code {response.status_code} - {response.text}") except Exception as e: # Handle network errors raise Exception(f"Error: {e}") ``` ------ ## 了解 `refreshNow` 參數 Secrets Manager Agent 會使用記憶體內快取來存放秘密值，它會定期重新整理。根據預設，當您在存留時間 (TTL) 過期後請求秘密時，通常會每 300 秒重新整理一次。不過，這種方法有時會導致秘密值過時，特別是當秘密在快取項目過期之前輪換時。 為了解決此限制，Secrets Manager Agent 支援 URL `refreshNow`中稱為 的參數。您可以使用此參數強制立即重新整理秘密的值、略過快取，並確保您擁有up-to-date資訊。 **預設行為 （不含 `refreshNow`)** + 使用快取值，直到 TTL 過期 + 僅在 TTL 之後重新整理秘密 （預設 300 秒） + 如果秘密在快取過期之前輪換，可能會傳回過時的值 **使用 的行為 `refreshNow=true`** + 完全略過快取 + 直接從 Secrets Manager 擷取最新的秘密值 + 使用新值更新快取並重設 TTL + 確保您一律取得最新的秘密值 ### 強制重新整理秘密值 **重要** `refreshNow` 的預設值為 `false`。設定為 時`true`，它會覆寫 Secrets Manager Agent 組態檔案中指定的 TTL，並對 Secrets Manager 進行 API 呼叫。 ------ #### [ curl ] **Example 範例 – 使用 curl 強制重新整理秘密** 下列 curl 範例顯示如何強制 Secrets Manager Agent 重新整理秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。 ``` curl -v -H \\ "X-Aws-Parameters-Secrets-Token: $(/var/run/awssmatoken)" \\ 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true' \\ echo ``` ------ #### [ Python ] **Example 範例 – 使用 Python 強制重新整理秘密** 下列 Python 範例示範如何從 Secrets Manager Agent 取得秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。 ``` import requests import json # Function that fetches the secret from Secrets Manager Agent for the provided secret id. def get_secret(): # Construct the URL for the GET request url = f"http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true" # Get the SSRF token from the token file with open('/var/run/awssmatoken') as fp: token = fp.read() headers = { "X-Aws-Parameters-Secrets-Token": token.strip() } try: # Send the GET request with headers response = requests.get(url, headers=headers) # Check if the request was successful if response.status_code == 200: # Return the secret value return response.text else: # Handle error cases raise Exception(f"Status code {response.status_code} - {response.text}") except Exception as e: # Handle network errors raise Exception(f"Error: {e}") ``` ------ ## 設定 Secrets Manager 代理程式 若要變更 Secrets Manager Agent 的組態，請建立 [TOML](https://toml.io/en/) 組態檔案，然後呼叫 `./aws_secretsmanager_agent --config config.toml`。組態選項 **`log_level`** Secrets Manager 代理程式日誌中報告的詳細資訊層級：DEBUG、INFO、WARN、 ERROR 或 NONE。預設值為 INFO。 **`log_to_file`** 是否要登入檔案或 stdout/stderr： `true`或 `false`。預設值為 `true`。 **`http_port`** 本機 HTTP 伺服器的連接埠，範圍介於 1024 到 65535 之間。預設值為 2773。 **`region`** AWS 用於請求的區域。如果未指定區域，Secrets Manager Agent 會從 SDK 判斷區域。如需詳細資訊，請參閱《適用於 *AWS Rust 的 SDK 開發人員指南*》中的[指定您的登入資料和預設區域](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。 **`ttl_seconds`** 快取項目的 TTL，以秒為單位，範圍介於 0 到 3600。預設值為 300。0 表示沒有快取。 **`cache_size`** 快取中可存放的秘密數目上限，範圍介於 1 到 1000。預設為 1000。 **`ssrf_headers`** Secrets Manager 代理程式會檢查 SSRF 字符的標頭名稱清單。預設值為「X-Aws-Parameters-Secrets-Token、X-Vault-Token」。 **`ssrf_env_variables`** Secrets Manager 代理程式會依序檢查 SSRF 字符的環境變數名稱清單。環境變數可以包含權杖或權杖檔案的參考，如 所示`AWS_TOKEN=file:///var/run/awssmatoken`。預設值為「AWS\$1TOKEN、AWS\$1SESSION\$1TOKEN、AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN」。 **`path_prefix`** 用來判斷請求是否為路徑型請求的 URI 字首。預設值為 "/v1/"。 **`max_conn`** Secrets Manager Agent 允許的最大 HTTP 用戶端連線數，範圍介於 1 到 1000。預設值為 800。 ## 選用功能 Secrets Manager Agent 可以透過將 `--features`旗標傳遞至 ，以選用功能建置`cargo build`。可用的功能包括：建構功能 **`prefer-post-quantum`** 建立最高優先順序`X25519MLKEM768`的金鑰交換演算法。否則，它可用，但不是最高優先順序。 `X25519MLKEM768` 是混合式、post-quantum-secure金鑰交換演算法。 **`fips`** 將代理程式使用的密碼套件限制為僅 FIPS 核准的密碼。 ## 日誌 **本機記錄** Secrets Manager Agent 會根據`log_to_file`組態變數，在本機將錯誤記錄到 檔案`logs/secrets_manager_agent.log`或 stdout/stderr。當您的應用程式呼叫 Secrets Manager 代理程式以取得秘密時，這些呼叫會出現在本機日誌中。它們不會出現在 CloudTrail 日誌中。 **日誌輪換** Secrets Manager 代理程式會在檔案達到 10 MB 時建立新的日誌檔案，並總共存放最多五個日誌檔案。 **AWS 服務記錄** 日誌不會移至 Secrets Manager、CloudTrail 或 CloudWatch。從 Secrets Manager Agent 取得秘密的請求不會出現在這些日誌中。當 Secrets Manager 代理程式呼叫 Secrets Manager 以取得秘密時，該呼叫會以包含 的使用者代理程式字串記錄在 CloudTrail 中`aws-secrets-manager-agent`。 您可以在 中設定記錄選項[設定 Secrets Manager 代理程式](#secrets-manager-agent-config)。 ## 安全考量 **信任網域** 對於代理程式架構，信任網域是可以存取代理程式端點和 SSRF 字符的地方，通常是整個主機。Secrets Manager 代理程式的信任網域應與可使用 Secrets Manager 登入資料的網域相符，以維持相同的安全狀態。例如，在 Amazon EC2 上，Secrets Manager Agent 的信任網域與使用 Amazon EC2 角色時的登入資料網域相同。 **重要** 尚未使用代理程式解決方案且已將 Secrets Manager 登入資料鎖定至應用程式的安全意識應用程式，應考慮使用語言特定的 AWS SDKs 或快取解決方案。如需詳細資訊，請參閱[取得秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。 # 使用 C\$1\$1 AWS SDK 取得 Secrets Manager 秘密值 對於 C\$1\$1 應用程式，請直接使用 [GetSecretValue](https://docs.aws.amazon.com/goto/SdkForCpp/secretsmanager-2017-10-17/GetSecretValue) 或 [BatchGetSecretValue](https://docs.aws.amazon.com/goto/SdkForCpp/secretsmanager-2017-10-17/BatchGetSecretValue) 呼叫 SDK。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` //! Retrieve an AWS Secrets Manager encrypted secret. /*! \param secretID: The ID for the secret. \return bool: Function succeeded. */ bool AwsDoc::SecretsManager::getSecretValue(const Aws::String &secretID, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::SecretsManager::SecretsManagerClient secretsManagerClient(clientConfiguration); Aws::SecretsManager::Model::GetSecretValueRequest request; request.SetSecretId(secretID); Aws::SecretsManager::Model::GetSecretValueOutcome getSecretValueOutcome = secretsManagerClient.GetSecretValue( request); if (getSecretValueOutcome.IsSuccess()) { std::cout << "Secret is: " << getSecretValueOutcome.GetResult().GetSecretString() << std::endl; } else { std::cerr << "Failed with Error: " << getSecretValueOutcome.GetError() << std::endl; } return getSecretValueOutcome.IsSuccess(); } ``` # 使用 JavaScript AWS SDK 取得 Secrets Manager 秘密值 對於 JavaScript 應用程序，請使用 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SecretsManager.html#getSecretValue-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SecretsManager.html#getSecretValue-property) 或 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SecretsManager.html#batchGetSecretValue-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SecretsManager.html#batchGetSecretValue-property) 直接呼叫 SDK。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` import { GetSecretValueCommand, SecretsManagerClient, } from "@aws-sdk/client-secrets-manager"; export const getSecretValue = async (secretName = "SECRET_NAME") => { const client = new SecretsManagerClient(); const response = await client.send( new GetSecretValueCommand({ SecretId: secretName, }), ); console.log(response); // { // '$metadata': { // httpStatusCode: 200, // requestId: '584eb612-f8b0-48c9-855e-6d246461b604', // extendedRequestId: undefined, // cfId: undefined, // attempts: 1, // totalRetryDelay: 0 // }, // ARN: 'arn:aws:secretsmanager:us-east-1:xxxxxxxxxxxx:secret:binary-secret-3873048-xxxxxx', // CreatedDate: 2023-08-08T19:29:51.294Z, // Name: 'binary-secret-3873048', // SecretBinary: Uint8Array(11) [ // 98, 105, 110, 97, 114, // 121, 32, 100, 97, 116, // 97 // ], // VersionId: '712083f4-0d26-415e-8044-16735142cd6a', // VersionStages: [ 'AWSCURRENT' ] // } if (response.SecretString) { return response.SecretString; } if (response.SecretBinary) { return response.SecretBinary; } }; ``` # 使用 Kotlin AWS SDK 取得 Secrets Manager 秘密值 對於 Kotlin 應用程式，請使用 [GetSecretValue](https://github.com/awslabs/aws-sdk-kotlin#generating-api-documentation) 或 [BatchGetSecretValue](https://github.com/awslabs/aws-sdk-kotlin#generating-api-documentation) 直接呼叫 SDK。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` suspend fun getValue(secretName: String?) { val valueRequest = GetSecretValueRequest { secretId = secretName } SecretsManagerClient.fromEnvironment { region = "us-east-1" }.use { secretsClient -> val response = secretsClient.getSecretValue(valueRequest) val secret = response.secretString println("The secret value is $secret") } } ``` # 使用 PHP AWS 開發套件取得 Secrets Manager 秘密值 對於 PHP 應用程序，請使用 [https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#getsecretvalue](https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#getsecretvalue) 或 [https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#batchGetsecretvalue](https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#batchGetsecretvalue) 直接呼叫 SDK。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` >/sdk-for-php/v3/developer-guide/guide_credentials.html */ // Create a Secrets Manager Client $client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => '<<{{MyRegionName}}>>', ]); $secret_name = '<<{{MySecretName}}>>'; try { $result = $client->getSecretValue([ 'SecretId' => $secret_name, ]); } catch (AwsException $e) { // For a list of exceptions thrown, see // https://<<{{DocsDomain}}>>/secretsmanager/latest/apireference/API_GetSecretValue.html throw $e; } // Decrypts secret using the associated KMS key. $secret = $result['SecretString']; // Your code goes here ``` # 使用 Ruby AWS 開發套件取得 Secrets Manager 秘密值 對於 Ruby 應用程序，請使用 [https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SecretsManager/Client.html#get_secret_value-instance_method](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SecretsManager/Client.html#get_secret_value-instance_method) 或 [https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SecretsManager/Client.html#batch_get_secret_value-instance_method](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SecretsManager/Client.html#batch_get_secret_value-instance_method) 直接呼叫 SDK。 下列程式碼範例顯示如何取得 Secrets Manager 秘密值。 **必要許可：**`secretsmanager:GetSecretValue` ``` # Use this code snippet in your app. # If you need more information about configurations or implementing the sample code, visit the AWS docs: # https://aws.amazon.com/developer/language/ruby/ require 'aws-sdk-secretsmanager' def get_secret client = Aws::SecretsManager::Client.new(region: '<<{{MyRegionName}}>>') begin get_secret_value_response = client.get_secret_value(secret_id: '<<{{MySecretName}}>>') rescue StandardError => e # For a list of exceptions thrown, see # https://<<{{DocsDomain}}>>/secretsmanager/latest/apireference/API_GetSecretValue.html raise e end secret = get_secret_value_response.secret_string # Your code goes here. end ``` # 使用 取得秘密值 AWS CLI **必要許可：**`secretsmanager:GetSecretValue` **Example 擷取機密的加密機密值** 下列 [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/get-secret-value.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/get-secret-value.html) 範例會取得目前機密值。 ``` aws secretsmanager get-secret-value \ --secret-id MyTestSecret ``` **Example 擷取先前的機密值** 下列 [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/get-secret-value.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/get-secret-value.html) 範例會取得先前的機密值。 ``` aws secretsmanager get-secret-value \ --secret-id MyTestSecret --version-stage AWSPREVIOUS ``` ## 使用 取得批次中的一組秘密 AWS CLI **必要許可：** + `secretsmanager:BatchGetSecretValue` + `secretsmanager:GetSecretValue` 您要擷取之每個秘密的 許可。 + 如果您使用過濾器，則還必須擁有 `secretsmanager:ListSecrets`。 如需許可政策範例，請參閱 [範例：擷取批次中一組秘密值的許可](auth-and-access_iam-policies.md#auth-and-access_examples_batch)。 **重要** 如果您的 VPCE 原則拒絕擷取您要擷取之群組中個別密碼的權限，則 `BatchGetSecretValue` 不會傳回任何秘密值，而且會傳回錯誤。 **Example 擷取按名稱列出的密碼群組的密碼值** 下列 [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/batch-get-secret-value.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/batch-get-secret-value.html) 範例會為三個秘密取得目前機密值。 ``` aws secretsmanager batch-get-secret-value \ --secret-id-list MySecret1 MySecret2 MySecret3 ``` **Example 擷取按篩選條件列出的密碼群組的密碼值** 下列 [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/batch-get-secret-value.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/batch-get-secret-value.html) 範例會取得具有名為「Test」之標籤之密碼的密碼值。 ``` aws secretsmanager batch-get-secret-value \ --filters Key="tag-key",Values="Test" ``` # 使用 AWS 主控台取得秘密值 **若要擷取秘密 (主控台)** 1. 前往以下位置開啟 Secrets Manager 主控台：[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。 1. 在秘密清單中，選擇您想要擷取的秘密。 1. 在 **Secret value (秘密值)** 區段，選擇 **Retrieve secret value (擷取秘密值)**。 Secrets Manager 會顯示秘密的目前版本 (`AWSCURRENT`)。若要查看秘密的[其他版本](whats-in-a-secret.md#term_version)，例如 `AWSPREVIOUS` 或自訂標記版本，請使用 [使用 取得秘密值 AWS CLI](retrieving-secrets_cli.md)。 # 在 中使用 AWS Secrets Manager 秘密 AWS Batch AWS Batch 可協助您在 上執行批次運算工作負載 AWS 雲端。使用 AWS Batch，您可以將敏感資料儲存在 AWS Secrets Manager 秘密中，然後在任務定義中參考它們，藉此將敏感資料注入任務。如需詳細資訊，請參閱[使用 Secrets Manager 指定敏感資料](https://docs.aws.amazon.com/batch/latest/userguide/specifying-sensitive-data-secrets.html)。 # 在 CloudFormation 資源中取得 AWS Secrets Manager 秘密 透過 CloudFormation，您可以擷取要在其他 CloudFormation 資源中使用的秘密。常見的案例是首先使用 Secrets Manager 產生的密碼建立秘密，然後從秘密中擷取使用者名稱和密碼，以用作新資料庫的憑證。如需使用 建立秘密的資訊 CloudFormation，請參閱 [在 中建立 AWS Secrets Manager 秘密 AWS CloudFormation](cloudformation.md)。 若要擷取 CloudFormation 範本中的秘密，您可以使用*動態參考*。當您建立堆疊時，動態參考會將秘密值提取到 CloudFormation 資源中，因此您不需要對秘密資訊進行硬式編碼。相對地，您就必須依名稱或 ARN 來參考秘密。您可以在任何資源屬性中將動態參考用於機密。您不能在資源中繼資料中將動態參考用於機密 (例如 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html))，因為這會使機密值在主控台中可見。 秘密的動態參考具有下列模式： ``` {{resolve:secretsmanager:secret-id:SecretString:json-key:version-stage:version-id}} ``` **secret-id** 秘密的名稱或 ARN。若要存取 AWS 帳戶中的秘密，您可以使用秘密名稱。若要存取不同 AWS 帳戶中的秘密，請使用秘密的 ARN。 **json-key** (選用) 您要擷取值的鍵值組的索引鍵名稱。如果您未指定 `json-key`， 會 CloudFormation 擷取整個秘密文字。此區段可能不可包含冒號字元 (`:`)。 **version-stage** (選用) 要使用的秘密[版本](whats-in-a-secret.md#term_version)。Secrets Manager 在輪換程序期間使用預備標籤來追蹤不同版本。如果您使用 `version-stage`，請不要指定 `version-id`。如果您未指定 `version-stage` 或 `version-id`，則預設為 `AWSCURRENT` 版本。此區段可能不可包含冒號字元 (`:`)。 **version-id** (選用) 您要使用的秘密版本的唯一識別碼。如果您指定 `version-id`，則請不要指定 `version-stage`。如果您未指定 `version-stage` 或 `version-id`，則預設為 `AWSCURRENT` 版本。此區段可能不可包含冒號字元 (`:`)。 如需詳細資訊，請參閱[使用動態參考指定 Secrets Manager 秘密](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#dynamic-references-secretsmanager)。 **注意** 請勿使用反斜線`(\)`做為最終值來建立動態參考。 CloudFormation 無法解析這些參考，這會導致資源失敗。 # 在 GitHub 任務中使用 AWS Secrets Manager 秘密 若要在 GitHub 任務中使用秘密，您可以使用 GitHub 動作從 擷取秘密， AWS Secrets Manager 並將其新增為 GitHub 工作流程中的遮罩[環境變數](https://docs.github.com/en/actions/learn-github-actions/environment-variables)。如需 GitHub Actions 的詳細資訊，請參閱 *GitHub Docs* (GitHub 文件) 中的 [Understanding GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) (瞭解 GitHub Actions)。 將秘密新增至 GitHub 環境時，GitHub 工作中的所有其他步驟都可以使用該秘密。請遵循 [Security hardening for GitHub Actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) (GitHub Actions 的安全性強化) 中的指引，協助防止您環境中的秘密遭到濫用。 您可以將秘密值的整個字串設定為環境變數值，或者如果字串為 JSON，您可以剖析 JSON，為每個 JSON 索引鍵值組設定個別環境變數。如果秘密值是二進位，此動作會將其轉換為字串。 若要檢視以您秘密建立的環境變數，請開啟偵錯記錄。如需詳細資訊，請參閱 *GitHub Docs* (GitHub 文件) 中的 [Enabling debug logging](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging) (啟用偵錯記錄)。 若要使用以秘密建立而成的環境變數，請參閱 *GitHub 文件*中的[環境變數](https://docs.github.com/en/actions/learn-github-actions/environment-variables)。 ## 先決條件 若要使用此動作，您首先需要設定 AWS 登入資料，並使用 `configure-aws-credentials` 步驟 AWS 區域 在 GitHub 環境中設定 。依照[針對 GitHub 動作設定 AWS 憑證動作](https://github.com/aws-actions/configure-aws-credentials)的指示操作，**使用 GitHub OIDC 供應商直接擔任角色**。這可讓您使用短期憑證，避免將其他存取金鑰儲存在 Secrets Manager 之外。 此動作擔任的 IAM 角色必須擁有下列許可： + 對您要擷取的秘密有 `GetSecretValue`。 + 對所有秘密有 `ListSecrets`。 + KMS key 如果秘密使用 加密，`Decrypt`則為 （選用） 客戶受管金鑰。 如需詳細資訊，請參閱[的身分驗證和存取控制 AWS Secrets Manager](auth-and-access.md)。 ## Usage 若要使用此動作，請新增步驟至使用下列語法的工作流程。 ``` - name: Step name uses: aws-actions/aws-secretsmanager-get-secrets@v2 with: secret-ids: | secretId1 ENV_VAR_NAME, secretId2 name-transformation: (Optional) uppercase|lowercase|none parse-json-secrets: (Optional) true|false ```Parameters `secret-ids` 秘密 ARN、名稱和名稱字首。 若要設定環境變數名稱，請在秘密 ID 前輸入名稱，然後加上英文逗號。例如，`ENV_VAR_1, secretId` 會以秘密 `secretId` 建立名為 **ENV\$1VAR\$11** 的環境變數。環境變數名稱可包含大寫字母、數字和底線。 若要使用字首，請輸入至少三個字元，然後加上星號。例如，`dev*` 會符合名稱以 **dev** 開頭的所有秘密。可擷取的相符秘密數上限為 100。如果您設定變數名稱，且字首與多個秘密相符，則動作會失敗。 `name-transformation` 此步驟預設會以秘密名稱建立每個環境變數名稱，環境變數名稱已轉換為只包含大寫字母、數字和底線，因此不會以數字開頭。對於名稱中的字母，您可以將步驟設定為使用小寫字母搭配 `lowercase`或 ，不要變更字母搭配 的大小寫`none`。預設值為 `uppercase`。 `parse-json-secrets` (選用) 此動作預設會將環境變數值設定為秘密值的整個 JSON 字串。`parse-json-secrets` 設定為 `true`以為 JSON 中的每個鍵值對建立環境變數。 請注意，如果 JSON 使用區分大小寫的索引鍵 (例如 "name" 和 "Name")，動作會有重複名稱衝突。在此情況下，請將 `parse-json-secrets` 設定為 `false`，並分別剖析 JSON 秘密值。 ## 環境變數命名 由 動作建立的環境變數，其名稱與其來源的秘密相同。環境變數具有比秘密更嚴格的命名要求，因此 動作會轉換秘密名稱以符合這些要求。例如，此動作會將小寫字母轉換為大寫字母。如果您剖析秘密的 JSON，環境變數名稱會同時包含秘密名稱和 JSON 金鑰名稱，例如 `MYSECRET_KEYNAME`。您可以設定動作，不要轉換小寫字母。 如果兩個環境變數最終名稱相同，則動作會失敗。在此情況下，您必須將要用於環境變數的名稱指定為*別名*。 名稱可能衝突的範例： + 名為 "MySecret" 的秘密和名為 "mysecret" 的秘密都會成為名為 "MYSECRET" 的環境變數。 + 名為 "Secret\$1keyname" 的秘密和名為 "Secret" 且金鑰名為 "keyname" 的 JSON 剖析秘密都會成為名為 "SECRET\$1KEYNAME" 的環境變數。 您可以指定*別名*來設定環境變數名稱，如下列範例所示，這會建立名為 的變數`ENV_VAR_NAME`。 ``` secret-ids: | ENV_VAR_NAME, secretId2 ``` **空白別名** + 如果您設定`parse-json-secrets: true`並輸入空白別名，後面接著逗號和秘密 ID，動作會將環境變數命名為與剖析的 JSON 金鑰相同的名稱。變數名稱不包含秘密名稱。 如果秘密不包含有效的 JSON，則動作會建立一個環境變數，並將其命名為與秘密名稱相同。 + 如果您設定`parse-json-secrets: false`並輸入空白別名，後面接著逗號和秘密 ID，動作會將環境變數命名為您未指定別名。 下列範例顯示空白別名。 ``` ,secret2 ``` ## 範例 **Example 1 依名稱和 ARN 取得秘密** 以下範例會為依名稱和 ARN 識別的秘密，建立環境變數。 ``` - name: Get secrets by name and by ARN uses: aws-actions/aws-secretsmanager-get-secrets@v2 with: secret-ids: | exampleSecretName arn:aws:secretsmanager:us-east-2:123456789012:secret:test1-a1b2c3 0/test/secret /prod/example/secret SECRET_ALIAS_1,test/secret SECRET_ALIAS_2,arn:aws:secretsmanager:us-east-2:123456789012:secret:test2-a1b2c3 ,secret2 ``` 建立的環境變數： ``` EXAMPLESECRETNAME: secretValue1 TEST1: secretValue2 _0_TEST_SECRET: secretValue3 _PROD_EXAMPLE_SECRET: secretValue4 SECRET_ALIAS_1: secretValue5 SECRET_ALIAS_2: secretValue6 SECRET2: secretValue7 ``` **Example 2 取得以字首開頭的所有秘密** 以下範例會為名稱以 *beta* 開頭的所有秘密，建立環境變數。 ``` - name: Get Secret Names by Prefix uses: 2 with: secret-ids: | beta* # Retrieves all secrets that start with 'beta' ``` 建立的環境變數： ``` BETASECRETNAME: secretValue1 BETATEST: secretValue2 BETA_NEWSECRET: secretValue3 ``` **Example 3 剖析秘密中的 JSON** 以下範例會剖析秘密中的 JSON，藉此建立環境變數。 ``` - name: Get Secrets by Name and by ARN uses: aws-actions/aws-secretsmanager-get-secrets@v2 with: secret-ids: | test/secret ,secret2 parse-json-secrets: true ``` 秘密 `test/secret` 具有以下秘密值。 ``` { "api_user": "user", "api_key": "key", "config": { "active": "true" } } ``` 秘密 `secret2` 具有以下秘密值。 ``` { "myusername": "alejandro_rosalez", "mypassword": "EXAMPLE_PASSWORD" } ``` 建立的環境變數： ``` TEST_SECRET_API_USER: "user" TEST_SECRET_API_KEY: "key" TEST_SECRET_CONFIG_ACTIVE: "true" MYUSERNAME: "alejandro_rosalez" MYPASSWORD: "EXAMPLE_PASSWORD" ``` **Example 4 使用小寫字母做為環境變數名稱** 下列範例會建立具有小寫名稱的環境變數。 ``` - name: Get secrets uses: aws-actions/aws-secretsmanager-get-secrets@v2 with: secret-ids: exampleSecretName name-transformation: lowercase ``` 已建立環境變數： ``` examplesecretname: secretValue ``` # 在 GitLab AWS Secrets Manager 中使用 AWS Secrets Manager 與 GitLab 整合。您可以利用 Secrets Manager 秘密來保護 GitLab 登入資料，使其不再於 GitLab 中進行硬式編碼。反之，當您的應用程式在 [GitLab CI/CD 管道中執行任務時，GitLab Runner](https://docs.gitlab.com/runner/) 會從 Secrets Manager 擷取這些秘密。 GitLab 若要使用此整合，您將在 [IAM 和 IAM 角色中建立 OpenID Connect (OIDC) 身分提供者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) AWS Identity and Access Management 。這可讓 GitLab Runner 存取您的 Secrets Manager 秘密。如需 GitLab CI/CD 和 OIDC 的詳細資訊，請參閱 [GitLab 文件](https://docs.gitlab.com/ci/cloud_services/aws/)。 ## 考量事項 如果您使用的是非公有 GitLab 執行個體，則無法使用此 Secrets Manager 整合。反之，請參閱[非公有執行個體的 GitLab 文件](https://docs.gitlab.com/ci/cloud_services/aws/#configure-a-non-public-gitlab-instance)。 ## 先決條件 若要將 Secrets Manager 與 GitLab 整合，請完成下列先決條件： 1. **建立 AWS Secrets Manager 秘密** 您需要一個 Secrets Manager 秘密，該秘密將在 GitLab 任務中擷取，並不需要硬式編碼這些登入資料。[設定 GitLab 管道](#configure-gitlab-pipeline)時，您將需要 Secrets Manager 秘密 ID。如需詳細資訊，請參閱[建立 AWS Secrets Manager 秘密](create_secret.md)。 1. **在 IAM 主控台中將 GitLab 設為 OIDC 提供者。** 在此步驟中，您將在 IAM 主控台中將 GitLab 設為 OIDC 供應商。如需詳細資訊，請參閱[建立 OpenID Connect (OIDC) 身分提供者](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_providers_create_oidc.html)和 [GitLab 文件](https://docs.gitlab.com/ci/cloud_services/aws/)。 在 IAM 主控台中建立 OIDC 提供者時，請使用下列組態： 1. 將 `provider URL`設定為您的 GitLab 執行個體。例如 **gitlab.example.com**。 1. 將 `audience`或 `aud`設定為 **sts.amazonaws.com**。 1. **建立 IAM 角色和政策** 您需要建立 IAM 角色和政策。此角色由 GitLab 使用 [AWS Security Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) 擔任。如需詳細資訊[，請參閱使用自訂信任政策建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-custom.html)。 1. 在 IAM 主控台中，建立 IAM 角色時使用下列設定： + 將 `Trusted entity type` 設定為 **Web identity**。 + 將 `Group` 設定為 **your GitLab group**。 + `Identity provider` 設定為您在步驟 2 中使用的相同提供者 URL ([GitLab 執行個體](#step2-oidc-provider))。 + `Audience` 設定為您在步驟 2 中使用的相同[對象](#step2-oidc-audience)。 1. 以下是允許 GitLab 擔任角色的信任政策範例。您的信任政策應列出您的 AWS 帳戶、GitLab URL 和[專案路徑](https://docs.gitlab.com/user/project/)。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRoleWithWebIdentity", "Principal": { "Federated": "arn:aws:iam::111122223333:oidc-provider/gitlab.example.com" }, "Condition": { "StringEquals": { "gitlab.example.com:aud": [ "sts.amazon.com" ] }, "StringLike": { "gitlab.example.com:sub": [ "project_path:mygroup/project-*:ref_type:branch-*:ref:main*" ] } } } ] } ``` 1. 您也需要建立 IAM 政策，以允許 GitLab 存取 AWS Secrets Manager。您可以將此政策新增至信任政策。如需詳細資訊，請參閱[建立 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:your-secret" } ] } ``` ## AWS Secrets Manager 與 GitLab 整合 完成先決條件後，您可以將 GitLab 設定為使用 Secrets Manager 來保護您的登入資料。 ### 設定 GitLab 管道以使用 Secrets Manager 您需要使用下列資訊更新 [GitLab CI/CD 組態檔案](https://docs.gitlab.com/ci/yaml/yaml_optimization/)： + 權杖設為 STS 的對象。 + Secrets Manager 秘密 ID。 + 在 GitLab 管道中執行任務時，您希望 GitLab Runner 擔任的 IAM 角色。 + 存放秘密 AWS 區域 的 。 GitLab 從 Secrets Manager 擷取秘密，並將該值存放在暫存檔案中。此檔案的路徑會儲存在 CI/CD 變數中，類似於[檔案類型 CI/CD 變數](https://docs.gitlab.com/ci/variables/#use-file-type-cicd-variables)。 以下是 GitLab CI/CD 組態檔案的 YAML 檔案程式碼片段： ``` variables: AWS_REGION: us-east-1 AWS_ROLE_ARN: 'arn:aws:iam::111122223333:role/gitlab-role' job: id_tokens: AWS_ID_TOKEN: aud: 'sts.amazonaws.com' secrets: DATABASE_PASSWORD: aws_secrets_manager: secret_id: "arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name" ``` 如需詳細資訊，請參閱 [GitLab Secrets Manager 整合文件](https://docs.gitlab.com/ci/secrets/aws_secrets_manager/)。 或者，您可以在 GitLab 中測試 OIDC 組態。如需詳細資訊[，請參閱 GitLab 文件以測試 OIDC 組態](https://docs.gitlab.com/ci/cloud_services/aws/#test-the-oidc-configuration)。 ## 疑難排解 以下可協助您針對將 Secrets Manager 與 GitLab 整合時可能遇到的常見問題進行疑難排解。 ### GitLab 管道問題 如果您遇到 GitLab 管道問題，請確保下列事項： + 您的 YAML 檔案格式正確。如需詳細資訊，請參閱 [GitLab 文件](https://docs.gitlab.com/ee/ci/yaml/)。 + 您的 GitLab 管道擔任正確的角色、具有適當的許可，以及存取正確的 AWS Secrets Manager 秘密。 ### 其他資源 下列資源可協助您疑難排解 GitLab 和 的問題 AWS Secrets Manager： + [GitLab OIDC 疑難排解](https://docs.gitlab.com/ci/cloud_services/aws/#troubleshooting) + [偵錯 GitLab CI/CD 管道](https://docs.gitlab.com/ee/ci/troubleshooting.html) + [疑難排解](ascp-eks-installation.md#troubleshooting) # 在 中使用 AWS Secrets Manager 秘密 AWS IoT Greengrass AWS IoT Greengrass 是將雲端功能擴展到本機裝置的軟體。這能讓裝置收集與分析更接近資訊來源的資料、自主回應本機裝置，在本機網路上安全地互相通訊。 AWS IoT Greengrass 可讓您使用 AWS IoT Greengrass 裝置中的服務和應用程式進行身分驗證，而不需要硬式編碼密碼、字符或其他秘密。您可以使用 在 cloud. AWS IoT Greengrass extends Secrets Manager 中 AWS Secrets Manager 安全地存放和管理秘密， AWS IoT Greengrass 以便您的連接器和 Lambda 函數可以使用本機秘密與服務和應用程式互動。 若要將秘密整合到 AWS IoT Greengrass 群組中，您可以建立參考 Secrets Manager 秘密的群組資源。此私密資源會使用相關聯的 ARN 來參考雲端私密。若要了解如何建立、管理和使用秘密資源，請參閱《 AWS IoT 開發人員指南》中的[使用秘密資源](https://docs.aws.amazon.com/greengrass/latest/developerguide/secrets-using.html)。 若要將秘密部署至 AWS IoT Greengrass 核心，請參閱將[秘密部署至 AWS IoT Greengrass 核心。](https://docs.aws.amazon.com/greengrass/latest/developerguide/secrets.html) # 在參數存放區中使用 AWS Secrets Manager 秘密 AWS Systems Manager 參數存放區為組態資料管理和秘密管理提供安全的階層式儲存。您可以存放密碼、資料庫字串和授權碼之類的資料做為參數值。不過，參數存放區不會為存放的秘密提供自動輪換服務。反之，參數存放區可讓您將秘密存放在 Secrets Manager 中，然後將該秘密當作參數存放區參數來參考。 當您使用 Secrets Manager 設定參數存放區時，`secret-id` 參數存放區需要在名稱字串之前加上正斜線 (/)。 如需詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[從參數存放區參數參考 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html)。