Problem

Most microservices might require non-functional feature such as queueing and retry, but it will become complicate when number of microservices increase and changes.

Also, some of the application might cannot be change (e.g. legacy / source code missing / external application) so it cannot be add these non-functional feature in application itself.

Solution

Setup the Ambassador proxy to handle non-functional feature, main applications are require to get request / send response via Ambassador.

Use Case

1. Legacy application which cannot implement such non-functional feature;
2. Share non-functional feature in different application;

Implementation

There are some tools which can role as ambassador, some representives as below:

1. Envoy
2. Nginx

Consideration

Compare with Sidecar

Sidecar is for each microservices and Ambassador can for group of microservices. As result, it is complex on manage each sidecar. For example, using Istio to centralize mange Envoy for each sidecar.

Compare with Adaptor

Adaptor is transform request / response between microservices and caller. Majorly it is for legacy application but it do not provide additional non-functional feature.

Reference:

1. The Distributed System ToolKit: Patterns for Composite Containers, Kubernetes Blog
   https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/
2. Ambassador pattern, Microsoft Learn
   https://learn.microsoft.com/en-us/azure/architecture/patterns/ambassador

To create a real file checksum, it can be done by Lambda trigger. With lambda function, it can create trigger to execute task when file uploaded. This demo, it it will use Java to create lambda trigger to create MD5 and SHA-256 checksum.

Pre-requests

1. AWS account should has sufficient privilege to create lambda function and list s3 buckets;
2. User account for execute Lambda function should be configurated;

Steps

1. Create Lambda function.
   In AWS Management Console, click Create Function, input Function name and select Runtime to Java 11 (Corretto), then click Create Function.
   
2. Add Trigger
   Open created trigger, click Add trigger.
   
3. Configure new trigger
   In Add trigger menu, select S3 as trigger, then select target bucket in Bucket dropdown. Optionally, it can add s3 object key prefix and suffix in Prefix and suffix textbox.
   After tick Recursive invocation consent, click Add.
   
4. Create gradle library project
   In command prompt / terminal create project with gradle command as below.

   gradle init

5. Add dependency.
   In build.gradle, add line below to setup dependency and build task.

   dependencies {
       implementation 'com.amazonaws:aws-lambda-java-core:1.2.1'
       implementation 'com.amazonaws:aws-lambda-java-events:3.9.0'
       runtimeOnly 'com.amazonaws:aws-lambda-java-log4j2:1.2.0'
   
       implementation 'software.amazon.awssdk:s3:2.17.9'
   
       // Use JUnit Jupiter for testing.
       testImplementation 'org.junit.jupiter:junit-jupiter:5.7.1'
   }
   
   task("buildZip", type: Zip) {
       from compileJava
       from processResources
       into("lib") {
           from configurations.runtimeClasspath
       }
   }
   
   test {
       useJUnitPlatform()
   }
   
   java {
       sourceCompatibility = JavaVersion.VERSION_11
       targetCompatibility = JavaVersion.VERSION_11
   }
   
   build.dependsOn buildZip
   

6. Add handler.
   Create new class file named GenerateChecksumEventHandler and add code below.

   import com.amazonaws.services.lambda.runtime.Context;
   import com.amazonaws.services.lambda.runtime.LambdaLogger;
   import com.amazonaws.services.lambda.runtime.RequestHandler;
   import com.amazonaws.services.lambda.runtime.events.models.s3.S3EventNotification;
   import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
   import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
   import software.amazon.awssdk.core.ResponseBytes;
   import software.amazon.awssdk.core.sync.RequestBody;
   import software.amazon.awssdk.services.s3.S3Client;
   import software.amazon.awssdk.services.s3.model.GetObjectRequest;
   import software.amazon.awssdk.services.s3.model.GetObjectResponse;
   import software.amazon.awssdk.services.s3.model.PutObjectRequest;
   import software.amazon.awssdk.services.s3.model.PutObjectResponse;
   import java.io.ByteArrayInputStream;
   import java.io.IOException;
   import java.io.InputStream;
   import java.security.DigestInputStream;
   import java.security.MessageDigest;
   import java.security.NoSuchAlgorithmException;
   import java.util.Arrays;
   
   public class ChecksumEventHandler implements RequestHandler<S3EventNotification, Void> {
       private static final String ENVIRONMENT_VARIABLE_ACCESS_KEY_ID="ACCESS_KEY_ID";
       private static final String ENVIRONMENT_VARIABLE_SECRET_ACCESS_KEY=SECRET_ACCESS_KEY";
   
       @Override
       public Void handleRequest(S3EventNotification input, Context context) {
           // Initial settings.
           LambdaLogger logger = context.getLogger();
           String s3AccessKeyId = System.getenv(ENVIRONMENT_VARIABLE_L2_REMOTE_ACCESS_KEY_ID);
           String s3SecretAccessKey = System.getenv(ENVIRONMENT_VARIABLE_L2_REMOTE_SECRET_ACCESS_KEY);
   
           // Connect to s3 with specific access key and secret access key which store in environment variable.
           AwsBasicCredentials awsCredentials = AwsBasicCredentials.create(
                   s3AccessKeyId,
                   s3SecretAccessKey);
           S3Client s3Client = S3Client.builder().credentialsProvider(StaticCredentialsProvider.create(awsCredentials)).build();
   
           // Loop with uploaded files.
           input.getRecords().forEach(o-> {
               // Get related s3 object metadata and content.
               String bucketName = o.getS3().getBucket().getName();
               String objectKey = o.getS3().getObject().getKey();
               GetObjectRequest getObjectRequest = GetObjectRequest.builder().bucket(bucketName).key(objectKey).build();
               ResponseBytes<GetObjectResponse> response = s3Client.getObjectAsBytes(getObjectRequest);
               InputStream objectByte = new ByteArrayInputStream(response.asByteArray());
   
               // Generate checksum file and store in same bucket.
               generateChecksumFile(logger, bucketName, objectKey, objectByte, "MD5", "md5", s3Client);
               generateChecksumFile(logger, bucketName, objectKey, objectByte, "SHA-256", "sha256", s3Client);
           });
           return null;
       }
   
       /**
        * Generate checksum with specific algorithm.
        * @param logger injected logger.
        * @param bucketName s3 bucket name.
        * @param objectKey s3 object key name.
        * @param inputStream s3 object input stream.
        * @param algorithm checksum algorithm required.
        * @param fileExtension checksum file extension.
        * @param s3Client injected s3 client.
        */
       private void generateChecksumFile(LambdaLogger logger, String bucketName, String objectKey, InputStream inputStream, String algorithm, String fileExtension, S3Client s3Client) {
           try {
               inputStream.reset();
               String checksum = generateChecksum(inputStream, algorithm);
               logger.log(algorithm+ " checksum = "+ checksum);
               String checksumObjectName = objectKey+ "." +fileExtension;
               RequestBody s3ObjectBody = RequestBody.fromString(checksum);
               PutObjectRequest putObjectRequest = PutObjectRequest.builder().bucket(bucketName).key(checksumObjectName).build();
               PutObjectResponse putObjectResponse = s3Client.putObject(putObjectRequest, s3ObjectBody);
               logger.log("Checksum stored and upload to bucket "+bucketName+"; path = "+ checksumObjectName+ ", e-tag = "+putObjectResponse.eTag()+".");
           } catch (NoSuchAlgorithmException | IOException e) {
               logger.log(e.getMessage());
               logger.log(Arrays.toString(e.getStackTrace()));
           }
       }
   
       /**
        * Generate checksum with specific algorithm.
        * @param inputStream object stream to be hash.
        * @param algorithm checksum algorithm.
        * @return Checksum in string format.
        * @throws NoSuchAlgorithmException Invalid input algorithm.
        * @throws IOException Exception when read / write byte.
        */
       private String generateChecksum(InputStream inputStream, String algorithm) throws NoSuchAlgorithmException, IOException {
           MessageDigest messageDigest = MessageDigest.getInstance(algorithm);
   
           DigestInputStream digestInputStream = new DigestInputStream(inputStream, messageDigest);
           byte[] buffer = new byte[4096];
           int count = 0;
           while (digestInputStream.read(buffer) > -1) {
               count++;
           }
           MessageDigest digest = digestInputStream.getMessageDigest();
           digestInputStream.close();
   
           byte[] checksum = digest.digest();
           StringBuilder sb = new StringBuilder();
           for (byte b : checksum) {
               sb.append(String.format("%02X", b));
           }
           return sb.toString().toUpperCase();
       }
   }
   

   As it will generate file and upload to s3 bucket, so it is required to use AWS SDK and put object permission.

7. Build distributed file.
   In command prompt / terminal, execute command below.

   gradle clean buildZip

8. Upload file.
   In Lambda function, select Code tab, click Upload From > zip of jar file, select built file and upload it.
   
9. Add credential.
   In lambda function, select Configuration > Environment variables, click Edit, then add parameter below and set access key and secret key.
   
10. Create Test
    In lambda function, select Test tab, click new event and input event name, then input json below. Beware bucket name, arn and object key should align with triggered s3 bucket and its object.
    

11. {
      "Records": [
        {
          "eventVersion": "2.0",
          "eventSource": "aws:s3",
          "awsRegion": "ap-southeast-1",
          "eventTime": "1970-01-01T00:00:00.000Z",
          "eventName": "ObjectCreated:Put",
          "requestParameters": {
            "sourceIPAddress": "127.0.0.1"
          },
          "responseElements": {
            "x-amz-request-id": "EXAMPLE123456789",
            "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH"
          },
          "s3": {
            "bucket": {
              "name": "test-bucket",
              "arn": "arn:aws:s3:::test-bucket"
            },
            "object": {
              "key": "test.zip"
            }
          }
        }
      ]
    }

12. Execute test.
    Click Test to execute test, expected it will result success.
    

In this demo, it will use springboot actuator to capture metric and AWS cloudwatch to render it out.Steps as below:

1. Add related library.
   In build.gradle, add dependency as below.

   dependencies {
       compile('org.springframework.boot:spring-boot-starter-web')
       compile('org.springframework.cloud:spring-cloud-starter-aws:2.2.5.RELEASE')
       compile('org.springframework.boot:spring-boot-starter-aop')
       compile("org.springframework.boot:spring-boot-starter-actuator")
       compile('org.springframework.cloud:spring-cloud-aws-actuator:2.2.5.RELEASE')
   }

2. Add annotation in Main application.
   In application.java, alter code as below.

   @EnableAspectJAutoProxy
   @SpringBootApplication
   @EnableAutoConfiguration(exclude = {ContextInstanceDataAutoConfiguration.class})
   @EnableScheduling
   public class Application {
       public static void main(String[] args) {
           SpringApplication.run(Application.class, args);
       }
   }
   

    

3. Create metrics and register in Meter Registry.
   Create controller DiagnoisisController and alter code as below.

   @RestController("DiagnosisController")
   @RequestMapping(value ="/v1/diagnosis")
   public class DiagnosisController {
       @Autowired
       DiagnosisService diagnosisService;
   
       public static final long METRIC_RELOAD_INTERVAL=10000;
       public static final String METRIC CLIENT_COUNT="connection.count";
       public static final String METRIC_THALES_CLIENT_COMPLETED_TASK_COUNT="client.completed.tasks";
   
       private final AtomicInteger currentHsmClientCount;
       private final Counter currentThalesClientCompletedTaskCount;
   
       public DiagnosisController(MeterRegistry meterRegistry) throws Exception {
           currentHsmClientCount=meterRegistry.gauge(METRIC_HSM_CLIENT_COUNT, new AtomicInteger());
           currentThalesClientCompletedTaskCount= Counter.builder(METRIC_THALES_CLIENT_COMPLETED_TASK_COUNT).description("Thales client completed tasks.").register(meterRegistry);
       }
   
       @Scheduled(fixedRate = METRIC_RELOAD_INTERVAL)
       public void updateMetric() throws Throwable {
           ServiceStatus serviceStatus=diagnosisService.status(false);
           currentHsmClientCount.set(serviceStatus.getCurrentClientCount());
           currentThalesClientCompletedTaskCount.increment(serviceStatus.getCurrentClientCompletedTaskCount());
       }
   }

   Method updateMetric() is used to update metric value with schedule job. Normally it can return object count / size, but my case is return service response so it’s not valid in there.

4. Add AWS metric properties.
   In application.properties, add settings as below.

   ## Springboot Actuator settings.
   management.endpoint.health.show-details=always
   management.endpoints.web.exposure.include=*
   management.health.db.enabled=true
   
   ## AWS Cloudwatch settings.
   cloud.aws.region.static=[[AWS available zone code]]
   cloud.aws.stack.auto = false
   management.metrics.export.cloudwatch.namespace=[Display name in CloudWatch]
   management.metrics.export.cloudwatch.batchSize=20

5. Check result locally.
   Run debug in IDE, open /actuator/metrics/ , see custom metric found or not. Expected it is exists.
   
6. Check result in CloudWatch
   After deploy to AWS EC2 instance, CloudWatch will capture metric automatically.
   

1. Create AWS CodeArtifact Domain.
   In AWS CodeArtifact, select Domains > Create Domain. Input domain name and click button Create Domain.
   
2. Create Repository.
   In AWS CodeArtifact, select Repository > Create Repository, input Repository name and click Next.
   
3. Select Repository’s domain.
   Select AWS account to This AWS account and select related Domain, then click Next.
   
4. Confirm repository settings and create.
   After review settings, then click Create Repository.
   
5. Setup Maven repository settings for local computer
   Create file setting.xml in %USER%\.m2\

   <settings>
     <servers>
       <server>
         <id>CodeArtifact</id>
         <username>aws</username>
         <password>${env.CODEARTIFACT_AUTH_TOKEN}</password>
       </server>
       </servers>
   <mirrors>
     <mirror>
       <id>CodeArtifact</id>
       <name>CodeArtifact</name>
       <url>https://{{domain-name}}-{{domain-id}}.d.codeartifact.ap-southeast-1.amazonaws.com/maven/{{repo-name}}/</url>
       <mirrorOf>*</mirrorOf>
     </mirror>
   </mirrors>
   </settings>

6. Generate AWS authentication token and store in variable.
   In command prompt / bash, execute command and store variable in CODEARTIFACT_AUTH_TOKEN.

   :: For Windows:
   FOR /F "tokens=*" %a in ('aws codeartifact get-authorization-token --domain {{domain-name}} --domain-owner {{domain-id}} --query authorizationToken --output text') do SET CODEARTIFACT_AUTH_TOKEN=%a
   
   :: For Linux: 
   export CODEARTIFACT_AUTH_TOKEN=`aws codeartifact get-authorization-token --domain {{domain-name}} --domain-owner {{domain-id}} --query authorizationToken --output text`

7. Update project settings.
   Edit pom.xml (for Maven project) / build.gradle (for Gradle project).
   pom.xml

   <project>
   ...
     <groupId>com.test</groupId>
     <artifactId>demo</artifactId>
     <version>1.0.1</version>
     <packaging>jar</packaging>
     <name>demo</name>
   ...
     <distributionManagement>
     	<repository>
           <id>d-sg-2--d-sg-ca-repo</id>
           <name>aws-codeArtifact</name>
           <url>https://{{domain-name}}-{{domain-id}}.d.codeartifact.ap-southeast-1.amazonaws.com/maven/{{repo-name}}/</url>
     	</repository>
     </distributionManagement>
   ...
   </project>

   build.gradle

   ...
   plugins {
       id 'maven-publish'
   }
   ...
   ext {
       // Package metadata.
       packageGroup = 'com.test'
       artifact='demo'
       packageName = 'demo'
       packageVersion = '1.0.1'
   }
   ...
   repositories {
       //mavenCentral()
       //mavenLocal()
       maven {
         url 'https://{{domain-name}}-{{domain-id}}.d.codeartifact.ap-southeast-1.amazonaws.com/maven/{{repo-name}}/'
         credentials {
             username "aws"
             password System.env.CODEARTIFACT_AUTH_TOKEN
         }
       }
   }
   ...
   publishing {
       publications {
           mavenJava(MavenPublication) {
           	groupId="${packageGroup}"
               artifactId="${packageName}"
               version="${packageVersion}"
               from components.java
           }
       }
       repositories {
         // AWS CodeArtifact
         maven {
             url 'https://{{domain-name}}-{{domain-id}}.d.codeartifact.ap-southeast-1.amazonaws.com/maven/{{repo-name}}/'
             credentials {
                 username "aws"
                 password System.env.CODEARTIFACT_AUTH_TOKEN
             }
         }
       }
   }
   ...

8. Publish to AWS CodeArtifact.
   In command prompt / bash, execute command.

   ::Maven project.
   mvn deploy
   
   ::Gradle project.
   gradle publish

   

9. Verify delivery.
   In CodeArtifact, click Repositories > select repository, see published package found or not.
   

然而, 在若果將業務放到公有雲上, 雖然一次性的建立成本會低, 但其營運成本便相對較高, 除了服務費用 (Service Charge), 替換成本(Switching Cost)及將公司敏感資料放到網上而洩密(Data leakage)等風險成本亦會出現. 因此, 部份公司亦會決定自己架構私有雲(Private Cloud). 若要做到類似Google 和Microsoft 相類似的話, 首推NextCloud.

NextCloud 是一套Opensource platform 可以存取檔案, 聯絡人, 行事曆, 還可以加建add-on, 加入email client / GPX tracker 等, 方便地打造適合自己使用的平台.

Reference

• NextCloud
• AppStore, NextCloud