Microservices Engine:Configuration encryption

Create an encrypted configuration

Follow these steps to create an encrypted configuration in the MSE console.

1. Log on to the MSE console, and select a region in the top navigation bar.

2. In the left-side navigation pane, choose Microservices Registry > Instances.

3. On the Instances page, click the name of the instance.

4. In the left-side navigation pane, choose Configuration Management > Configurations.

5. In the upper-left corner of the Configurations page, select a namespace from the Namespace drop-down list, and click Add Configuration.

6. In the Create Configuration panel, enter the Data ID and Group, enable the Data Encryption switch, and then select a KMS Key. If you do not have a KMS Key, click Create. You can create a key in the Key Management Service console. After the key is created, you can refresh the Create Configuration panel to view the new KMS key.

   Important

   • If you activated Dedicated KMS after March 31, 2022, you must select the Key ID to use for encryption and associate the Key ID with the Nacos instance. All subsequent configurations will then be encrypted using this key.

   • If you are not prompted to associate the key ID of a Dedicated KMS instance, it means you activated KMS before March 31, 2022 and can still use Shared KMS. The configuration methods for applications to access Shared KMS are different.

   • For users who use Dedicated KMS, KMS AES-256 encryption is displayed. For backward compatibility, three encryption methods are displayed for users who use an earlier version of Shared KMS. However, we recommend that you do not use KMS encryption or KMS AES-128 encryption.

     • KMS AES-256 encryption: This method uses the KMS envelope encryption and decryption method with a 256-bit key, providing high encryption strength. The size of the encrypted configuration content cannot exceed 50 KB. Plaintext configuration data is not transmitted to the KMS system. This method provides higher security and is recommended. Select an encryption method based on your needs.

     • KMS AES-128 encryption: This method uses a 128-bit key and provides medium encryption strength. The size of the encrypted configuration content cannot exceed 50 KB.

     • KMS encryption: This method is not recommended because it has compatibility issues with special characters (for example, the & symbol is escaped as \u0026) and the encrypted configuration content cannot exceed 6 KB.

   • After a key is associated, you cannot change the key for the MSE Nacos instance. If you delete the key, you will lose access to the encrypted configurations.

7. In the Configuration Format section, select a data format, enter the content in the Configuration Content text box on the right, and then click Release.

Use an encrypted configuration in Nacos SDK for Java

1. Add the following dependencies to the pom.xml file in the project.

   <dependency>
       <groupId>com.alibaba.nacos</groupId>
       <artifactId>nacos-client</artifactId>
       <version>{nacos-client-version}</version>
   </dependency>
   <dependency>
       <groupId>com.alibaba.nacos</groupId>
       <artifactId>nacos-client-mse-extension</artifactId>
       <version>{nacos-client-mse-extension-version}</version>
   </dependency>

   Version guide

   Nacos client major version	Nacos client version	Recommended plugin version
   1.x	1.4.3 or later	1.0.6 or later
   2.x	2.1.1 or later	1.0.6 or later

   Important

   Stability issues may occur if the encryption and decryption plugin version does not match the Nacos client version. We recommend that you use the recommended versions.

2. Configure the code based on the framework you use.

   Use Nacos Client directly

   If you use the Nacos Client framework to retrieve configurations, use the following sample code.

   try {
       Properties properties = new Properties();
       // The endpoint of your Nacos cluster.
       properties.put("serverAddr", "{serverAddr}");
       // Configure the RAM role of the ECS instance as the access credential.
       properties.put("ramRoleName", "{ramRoleName}");
       // The endpoint of the KMS instance.
       properties.put("kmsEndpoint", "{kmsEndpoint}");
       ConfigService configService = NacosFactory.createConfigService(properties);
       System.out.println("content:::"+configService.getConfig("{dataId}", "{group}", 6000));
   } catch (Exception e) {
       e.printStackTrace();
   }

   The kmsEndpoint parameter specifies the endpoint of the KMS instance. If the application and the KMS instance are in the same VPC, set this parameter to the VPC endpoint of the instance. If you access the KMS instance over the Internet, set this parameter to the public endpoint or the VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?

   If you use an AccessKey pair for authentication, replace the following configuration:

   properties.put("ramRoleName", "{ramRoleName}");

   with the following configuration:

   properties.put("accessKey", "{accessKey}"); 
   properties.put("secretKey", "{secretKey}");

   The Nacos SDK for Java supports multiple access credentials for encrypted configurations, such as Security Token Service (STS) tokens and the Alibaba Cloud Resource Name (ARN) of a RAM role. For more information about supported access credentials and client configuration methods, see Supported access credentials for configuration encryption.

   If you activated KMS after March 31, 2022, and want to publish encrypted configurations from the SDK, add the following code:

   properties.put("keyId", "{keyId}");

   Replace the serverAddr, ramRoleName, accessKey, secretKey, kmsEndpoint, dataId, group, and keyId parameters in the code with your actual service parameters.

   Use the Spring Cloud Nacos Config framework

   Note

   • If you use Spring Cloud Alibaba 2022.x or 2023.x, upgrade the version to 2023.0.1.2.

   • If you use Spring Cloud Alibaba 2021.x, upgrade the version to 2021.0.6.1.

   • If you use Spring Cloud Alibaba 2.x, upgrade the version to 2.2.10.

   • Make sure that the version mappings among Spring Cloud Alibaba, Spring Cloud, and Spring Boot are correct. For more information about the version mappings, see the release notes for the related branch on the Spring Cloud Alibaba official website.

   If you use the Spring Cloud Nacos Config framework to retrieve configurations, add the following configurations.

   spring.cloud.nacos.config.server-addr={serverAddr}
   spring.config.import=nacos:{dataId}?group={group}&refreshEnabled=true
   # Configure the RAM role of the ECS instance as the access credential.
   spring.cloud.nacos.config.ramRoleName={ramRoleName}
   spring.cloud.nacos.config.kmsEndpoint={kmsEndpoint}

   The kmsEndpoint parameter specifies the endpoint of the KMS instance. If the application and the KMS instance are in the same VPC, set this parameter to the VPC endpoint of the instance. If you access the KMS instance over the Internet, set this parameter to the public endpoint or the VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?

   If you use an AccessKey pair for authentication, replace the following configuration:

   spring.cloud.nacos.config.ramRoleName={ramRoleName}

   with the following configurations:

   spring.cloud.nacos.config.accesskey={accessKey}
   spring.cloud.nacos.config.secretkey={secretKey}
   
   # If an AccessKey pair is used to access your Nacos instance, we recommend that you specify the AccessKey pair using JVM parameters or environment variables due to the particularity of the parameters.
   # JVM parameters
   -Dspring.cloud.nacos.config.accessKey={accessKey}
   -Dspring.cloud.nacos.config.secretKey={secretKey}
   # Environment variables
   spring_cloud_nacos_config_accessKey={accessKey}
   spring_cloud_nacos_config_secretKey={secretKey}

   The Nacos SDK for Java supports multiple access credentials for encrypted configurations, such as Security Token Service (STS) tokens and the Alibaba Cloud Resource Name (ARN) of a RAM role. For more information about supported access credentials and client configuration methods, see Supported access credentials for configuration encryption.

   If you activated KMS after March 31, 2022, and want to publish encrypted configurations from the SDK, add the following configuration:

   spring.cloud.nacos.config.keyId={keyId}

   Replace the serverAddr, ramRoleName, accessKey, secretKey, kmsEndpoint, dataId, group, and keyId parameters in the code with your actual service parameters.

   Parameter description

   Make sure that the following parameters are correctly set.

   Parameter	Description
   serverAddr	The endpoint of the MSE cluster. Example: mse-*****.nacos-ans.mse.aliyuncs.com.
   ramRoleName	The RAM role that is attached to the ECS instance or ACK cluster.
   accessKey, secretKey	The AccessKey ID and AccessKey secret of your Alibaba Cloud account. You can specify either the ramRoleName parameter or the accessKey and secretKey parameters.
   kmsEndpoint	The endpoint of the KMS instance. If the access environment and the KMS instance are in the same VPC, the value of kmsEndpoint is the VPC endpoint of the instance. If you access the KMS instance over the Internet, the value of kmsEndpoint is the public endpoint or VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?
   dataId	The data ID of the encrypted configuration. Example: cipher-kms-aes-256-****.properties.
   group	The group name of the encrypted configuration.
   keyId	The ID of the KMS key that is used to encrypt configurations. You can create and use a KMS key in the KMS console. Example: alia/*** or key-***.

Use an encrypted configuration in Nacos SDK for Go

1. Run the go get command to download the Nacos Client Go SDK dependencies.

   go get -u github.com/nacos-group/nacos-sdk-go/v2@v2.2.8

2. Modify the Nacos client initialization configuration.

   The Nacos SDK for Go only supports using an AccessKey pair as the credential to access the KMS instance. In the code, replace the serverAddr, accessKey, secretKey, and kmsEndpoint parameters with your business parameters and ensure that the OpenKMS: true parameter is set to enable configuration encryption.

   sc := []constant.ServerConfig{
     {
       IpAddr: "{serverAddr}", // Replace the value with the endpoint of your MSE instance.
       Port:   8848,
     },
   }
   var accessKey = "{accessKey}" 
   var secretKey = "{secretKey}" 
   
   cc := constant.ClientConfig{
     NamespaceId:         "public", // The ID of the namespace.
     OpenKMS:              true, // Enable KMS-based encryption for configurations.
     AccessKey:            accessKey, 
     SecretKey:            secretKey,
     KMSConfig:            &constant.KMSConfig{Endpoint: "{kmsEndpoint}",},
     TimeoutMs:           5000,
     NotLoadCacheAtStart: true,
     LogDir:              "/tmp/nacos/log",
     CacheDir:            "/tmp/nacos/cache",
     RotateTime:          "1h",
     MaxAge:              3,
   }

   The kmsEndpoint parameter specifies the endpoint of the KMS instance. If the application and the KMS instance are in the same VPC, set this parameter to the VPC endpoint of the instance. If you access the KMS instance over the Internet, set this parameter to the public endpoint or the VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?

3. Publish the encrypted configuration.

   keyId: The ID of the KMS key used for configuration encryption.

   configParam := vo.ConfigParam{
       DataId:   "{dataId}",
       Group:    "{group}",
       Content:  "content",
       KmsKeyId: "{keyId}",  // The ID of the KMS key that is used to encrypt configurations. You can create and use a KMS key in the KMS console.
   }
   
   published, err := client.PublishConfig(configParam)
   
   if published && err == nil {
   	fmt.Printf("successfully publish: group[%s], dataId[%s], data[%s]\n", configParam.Group, configParam.DataId, configParam.Content)
   } else {
     fmt.Printf("failed to publish: group[%s], dataId[%s], data[%s]\n with error: %s\n",
       configParam.Group, configParam.DataId, configParam.Content, err)
   }

Supported access credentials for configuration encryption

The Nacos SDK for Java supports multiple types of access credentials for configuration encryption. You can select an initialization method for the credential provider based on the authentication and authorization requirements of your scenario.

The Nacos SDK for Java supports the following types of access credentials:

• Use an AccessKey pair

• Use an STS token

• Use the ARN of a RAM role

• Use the RAM role of an ECS instance

• Use the RAM role of an OIDC IdP

• Use credentials URIs

For more information about how to configure access credentials on the client, see the configuration center section in Access authentication by the Nacos client. Grant the required permissions to the access credential by selecting the following system policy. This operation is a coarse-grained authorization that grants read and write permissions on all KMS instances.

FAQ

properties.put("kmsEndpoint", "{kmsEndpoint}");

properties.put("kms_region_id", "{kmsRegionId}");

spring.cloud.nacos.config.kmsEndpoint={kmsEndpoint}

spring.cloud.nacos.config.kms_region_id={kmsRegionId}

cc := constant.ClientConfig{
  NamespaceId:         "public", 
  OpenKMS:              true, 
  AccessKey:            accessKey, 
  SecretKey:            secretKey,
  KMSConfig:            &constant.KMSConfig{Endpoint: "{kmsEndpoint}",},
  TimeoutMs:            5000,
  NotLoadCacheAtStart:  true,
  LogDir:               "/tmp/nacos/log",
  CacheDir:             "/tmp/nacos/cache",
  RotateTime:           "1h",
  MaxAge:               3,
}

cc := constant.ClientConfig{
  NamespaceId:         "public", 
  OpenKMS:              true, 
  AccessKey:            accessKey, 
  SecretKey:            secretKey,
  TimeoutMs:            5000,
  NotLoadCacheAtStart:  true,
  LogDir:               "/tmp/nacos/log",
  CacheDir:             "/tmp/nacos/cache",
  RotateTime:           "1h",
  MaxAge:                3,
  RegionId:             "{kmsRegionId}",	
}

Troubleshooting

References

• System policies for Microservices Engine

• Custom policies for Microservices Engine (MSE)