Merge pull request #79 from AlibabaCloudLandingZone/solution-ecs-sts-token/0.0.7

solution-ecs-sts-token/0.0.7

Author: wibud

solution/solution-ecs-sts-token/code-example/java/common/src/main/java/org/example/oss_sdk/CredentialsDefaultSample.java

@@ -2,6 +2,7 @@
 
 import com.alibaba.fastjson2.JSON;
 import com.aliyun.credentials.Client;
+import com.aliyun.credentials.models.Config;
 import com.aliyun.credentials.models.CredentialModel;
 import com.aliyun.oss.*;
 import com.aliyun.oss.common.auth.Credentials;
@@ -18,7 +19,13 @@
 public class CredentialsDefaultSample {
     public static void main(String[] args) {
         // 初始化凭据客户端
-        Client credentialClient = new Client();
+        Config credentialConfig = new Config();
+        credentialConfig.setType("ecs_ram_role");
+        // 选填，该ECS角色的角色名称，不填会自动获取，建议加上以减少请求次数
+        credentialConfig.setRoleName("<your-ecs-instance-role-name>");
+        // 在加固模式下获取STS Token，强烈建议开启
+        credentialConfig.setEnableIMDSv2(true);
+        Client credentialClient = new Client(credentialConfig);
 
         // Bucket所在地域对应的Endpoint。以华东1（杭州）为例。
         String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

solution/solution-ecs-sts-token/code-example/java/common/src/main/java/org/example/oss_sdk/README.md

@@ -19,13 +19,10 @@ maven -version
 ### CredentialsDefaultSample
 该示例代码演示了初始化凭据客户端（初始化方式可参考sdk2中的示例，本示例采用默认凭据链方式），再使用凭据客户端的凭据信息初始化OSS客户端。
 
-Credentials工具会在环境变量中获取`ALIBABA_CLOUD_ECS_METADATA`（ECS实例RAM角色名称），若存在，程序将会通过ECS的元数据服务（Meta Data Server）获取ECS实例RAM角色的STS Token作为默认凭据信息。强烈建议配置环境变量`ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true`开启在加固模式下获取STS Token。
+> 强烈建议使用该方式，使用Credentials工具获取STS Token并初始化OSS客户端。
+
+Credentials工具会通过ECS的元数据服务（Meta Data Server）获取ECS实例RAM角色的STS Token作为默认凭据信息，并且支持到期自动刷新。
 
-在ECS中配置环境变量：
-```bash
-export ALIBABA_CLOUD_ECS_METADATA=<role-name>
-export ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true
-```
 运行示例代码：
 ```bash
 mvn exec:java -Dexec.mainClass="org.example.oss_sdk.CredentialsDefaultSample" -e -q
@@ -34,6 +31,8 @@ mvn exec:java -Dexec.mainClass="org.example.oss_sdk.CredentialsDefaultSample" -e
 ### RoleConfigSample
 该示例代码通过`InstanceProfileCredentialsProvider`配置ECS实例RAM角色，来初始化OSS客户端。
 
+> 不建议使用该方式，请参考`CredentialsDefaultSample.java`使用Credentials工具获取STS Token并初始化OSS客户端。
+
 运行示例代码：
 ```bash
 mvn exec:java -Dexec.mainClass="org.example.oss_sdk.RoleConfigSample" -e -q

solution/solution-ecs-sts-token/code-example/java/common/src/main/java/org/example/sdk2_0/README.md

@@ -20,9 +20,26 @@ java -version
 ```bash
 maven -version
 ```
+
+### CredentialsRoleConfigSample
+该示例代码采用显示配置ecs实例角色的方式初始化凭据客户端。
+
+> 推荐您使用该方式，在代码中明确指定实例角色，避免运行环境中的环境变量、配置文件等带来非预期的结果。
+
+该方式显示设置凭据类型为`ecs_ram_role`，Credentials工具会自动获取ECS实例绑定的RAM角色，调用ECS的元数据服务（Meta Data Server）换取STS Token，完成凭据客户端初始化。
+
+运行示例代码：
+```bash
+mvn exec:java -Dexec.mainClass="org.example.sdk2_0.CredentialsRoleConfigSample" -e -q
+```
+### 其他方式
+更多初始化方式，请参考[初始化凭据客户端](https://help.aliyun.com/zh/sdk/developer-reference/v2-manage-access-credentials)。
+
 ### CredentialsDefaultSample
 该示例代码采用默认凭据链的方式初始化凭据客户端。
 
+> 除非您清楚的知道默认凭据链中凭据信息查询优先级以及您的程序运行的各个环境中凭据信息配置方式，否则不建议您使用默认凭据链，推荐您使用显式配置实例角色方式。
+
 Credentials工具会在环境变量中获取`ALIBABA_CLOUD_ECS_METADATA`（ECS实例RAM角色名称），若存在，程序将会通过ECS的元数据服务（Meta Data Server）获取ECS实例RAM角色的STS Token作为默认凭据信息。强烈建议配置环境变量`ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true`开启在加固模式下获取STS Token。
 
 在ECS中配置环境变量：
@@ -34,15 +51,3 @@ export ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true
 ```bash
 mvn exec:java -Dexec.mainClass="org.example.sdk2_0.CredentialsDefaultSample" -e -q
 ```
-
-### CredentialsRoleConfigSample
-该示例代码采用显示配置ecs实例角色的方式初始化凭据客户端。
-
-该方式显示设置凭据类型为`ecs_ram_role`，Credentials工具会自动获取ECS实例绑定的RAM角色，调用ECS的元数据服务（Meta Data Server）换取STS Token，完成凭据客户端初始化。
-
-运行示例代码：
-```bash
-mvn exec:java -Dexec.mainClass="org.example.sdk2_0.CredentialsRoleConfigSample" -e -q
-```
-### 其他方式
-更多初始化方式，请参考[初始化凭据客户端](https://help.aliyun.com/zh/sdk/developer-reference/v2-manage-access-credentials)。

solution/solution-ecs-sts-token/code-example/java/common/src/main/java/org/example/sls_sdk/CredentialsDefaultSample.java

@@ -1,5 +1,6 @@
 package org.example.sls_sdk;
 
+import com.aliyun.credentials.models.Config;
 import com.aliyun.credentials.models.CredentialModel;
 import com.aliyun.openservices.log.Client;
 import com.aliyun.openservices.log.common.auth.DefaultCredentials;
@@ -16,7 +17,13 @@ public static void main(String[] args) throws LogException {
         String endpoint = "cn-hangzhou.log.aliyuncs.com";
 
         // 初始化凭据客户端
-        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
+        Config credentialConfig = new Config();
+        credentialConfig.setType("ecs_ram_role");
+        // 选填，该ECS角色的角色名称，不填会自动获取，建议加上以减少请求次数
+        credentialConfig.setRoleName("<your-ecs-instance-role-name>");
+        // 在加固模式下获取STS Token，强烈建议开启
+        credentialConfig.setEnableIMDSv2(true);
+        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialConfig);
 
         // 用凭据客户端初始化SLS客户端
         Client slsClient = createSlsClientByCredentials(endpoint, credentialClient);

solution/solution-ecs-sts-token/code-example/java/common/src/main/java/org/example/sls_sdk/README.md

@@ -19,13 +19,10 @@ maven -version
 ### CredentialsDefaultSample
 该示例代码演示了初始化凭据客户端（初始化方式可参考sdk2中的示例，本示例采用默认凭据链方式），再使用凭据客户端的凭据信息初始化SLS客户端。
 
-Credentials工具会在环境变量中获取`ALIBABA_CLOUD_ECS_METADATA`（ECS实例RAM角色名称），若存在，程序将会通过ECS的元数据服务（Meta Data Server）获取ECS实例RAM角色的STS Token作为默认凭据信息。强烈建议配置环境变量`ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true`开启在加固模式下获取STS Token。
+> 强烈建议使用该方式，使用Credentials工具获取STS Token并初始化SLS客户端。
+
+Credentials工具会通过ECS的元数据服务（Meta Data Server）获取ECS实例RAM角色的STS Token作为默认凭据信息，并且支持到期自动刷新。
 
-在ECS中配置环境变量：
-```bash
-export ALIBABA_CLOUD_ECS_METADATA=<role-name>
-export ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true
-```
 运行示例代码：
 ```bash
 mvn exec:java -Dexec.mainClass="org.example.sls_sdk.CredentialsDefaultSample" -e -q
@@ -34,6 +31,8 @@ mvn exec:java -Dexec.mainClass="org.example.sls_sdk.CredentialsDefaultSample" -e
 ### RoleConfigSample
 该示例代码通过显示配置ECS实例RAM角色，来初始化SLS客户端。
 
+> 不建议使用该方式，请参考`CredentialsDefaultSample.java`使用Credentials工具获取STS Token并初始化SLS客户端。
+
 运行示例代码：
 ```bash
 mvn exec:java -Dexec.mainClass="org.example.sls_sdk.RoleConfigSample" -e -q

solution/solution-ecs-sts-token/code-example/java/spring-boot/src/main/java/org/example/config/CredentialConfig.java

@@ -9,7 +9,22 @@
 public class CredentialConfig {
 
     // 初始化凭据客户端
+    // 您可以在代码中显式配置，来初始化凭据客户端
+    // 荐您使用该方式，在代码中明确指定实例角色，避免运行环境中的环境变量、配置文件等带来非预期的结果。
+    @Bean(name = "credentialClient")
+    Client getCredentialClient() {
+       Config config = new Config()
+           .setType("ecs_ram_role")
+           // 选填，该ECS实例角色的角色名称，不填会自动获取，建议加上以减少请求次数
+           .setRoleName("<请填写ECS实例角色的角色名称>")
+           // 在加固模式下获取STS Token，强烈建议开启
+           .setEnableIMDSv2(true);
+       return new Client(config);
+    }
+
+    // 您也可以使用Credentials工具的默认凭据链方式初始化凭据客户端
     // 借助Credentials工具的默认凭据链，您可以用同一套代码，通过程序之外的配置来控制不同环境下的凭据获取方式
+    // 除非您清楚的知道默认凭据链中凭据信息查询优先级以及您的程序运行的各个环境中凭据信息配置方式，否则不建议您使用默认凭据链
     // 当您在初始化凭据客户端不传入任何参数时，Credentials工具将会尝试按照如下顺序查找相关凭据信息（优先级由高到低）：
     // 1. 使用系统属性
     // 2. 使用环境变量
@@ -18,20 +33,8 @@ public class CredentialConfig {
     // 5. 使用ECS实例RAM角色（需要通过环境变量 ALIBABA_CLOUD_ECS_METADATA 指定 ECS 实例角色名称；通过环境变量 ALIBABA_CLOUD_ECS_IMDSV2_ENABLE=true 开启在加固模式下获取STS Token）
     // https://help.aliyun.com/zh/sdk/developer-reference/v2-manage-access-credentials#3ca299f04bw3c
     // 要使用默认凭据链，初始化 Client 时，必须使用空的构造函数，不能配置 Config 入参
-    @Bean(name = "credentialClient")
-    Client getCredentialClient() {
-        return new Client();
-    }
-
-    // 除了使用上面的默认凭据链，您也可以在代码中显式配置，来初始化凭据客户端
-    //@Bean(name = "credentialClient")
-    //Client getCredentialClient() {
-    //    Config config = new Config()
-    //        .setType("ecs_ram_role")
-    //        // 选填，该ECS实例角色的角色名称，不填会自动获取，建议加上以减少请求次数
-    //        .setRoleName("<请填写ECS实例角色的角色名称>")
-    //        // 在加固模式下获取STS Token，强烈建议开启
-    //        .setEnableIMDSv2(true);
-    //    return new Client(config);
-    //}
+    // @Bean(name = "credentialClient")
+    // Client getCredentialClient() {
+    //     return new Client();
+    // }
 }