Expose a Lattice Service Network service in a TSE EKS cluster

Make Lattice-hosted services available within a TSE cluster

Tetrate Service Express (TSE) can automatically add Lattice-hosted services to a TSE cluster. These services can then be discovered and consumed by TSE-hosted clients.

Feature Status: Experimental

Lattice Integration is currently released as an early preview of the capability. Please provide feedback, but do not rely on this feature in a production environment.

How does the integration work?

The TSE Management Plane uses an AWS Controller service to manage Lattice ServiceEntries in TSE Workload Clusters. The AWS Controller component is shipped with TSE and supported by Tetrate. It is not installed by default, and can be added to the Management Plane when needed.

You must first associate the TSE Management Plane cluster's VPC and one or more Workload cluster's VPCs with the Lattice Service network. You then tag the Lattice Services you wish to expose within the TSE cluster, and the AWS Controller finds these services and makes them available with the TSE workload clusters.

Expose Lattice service to TSE

Prior Configuration

These instructions build on the configuration created in the previous Expose a TSE-hosted Service to a local Lattice Service Network exercise. They assume you have a Lattice Service Network with two VPC associations:

• The first associates a VPC used by an EC2 virtual machine or other service
• The second associates the VPC used by a TSE EKS workload cluster

If you use the same cluster for TSE's Management Plane and for TSE-managed Workloads, and you associated that cluster's VPC with the Lattice Service Network in the previous exercise, you are ready to proceed. If not, please configure the following Service Network VPC associations:

1. VPC for the TSE EKS Management Plane cluster
2. VPCs for one or more TSE EKS Workload clusters

... in addition to the VPC used by an EC2 virtual machine or other service.

Configure the TSE Management Plane

Prerequisites

Before you proceed, you should have:

1. A Lattice Service Network in your selected region, containing a Lattice service that you wish to access from your TSE EKS cluster. The instructions below explain how to create a simple test service if necessary
2. A TSE Management Plane cluster in that region, associated with the Lattice Service Network
3. One or more TSE Workload clusters in that region, associated with the Lattice Service Network

Create an IAM Policy

You can re-use the AllowVPCLatticeUpdates policy created in the previous exercise, or create a dedicated (and more limited, read-only) policy for the TSE Management Plane:

cat <<EOF > AllowVPCLatticeReadOnly.yaml
{
  "Version" : "2012-10-17",
  "Statement" : [
    {
      "Effect" : "Allow",
      "Action" : [
        "vpc-lattice:ListListeners",
        "vpc-lattice:ListServices",
        "vpc-lattice:ListServiceNetworkServiceAssociations",
        "vpc-lattice:ListTagsForResource"
      ],
      "Resource" : "*"
    }
  ]
}
EOF

POLICY_NAME=AllowVPCLatticeReadOnly
aws iam create-policy --policy-name ${POLICY_NAME} --policy-document file://AllowVPCLatticeReadOnly.yaml

Configure the TSE Management Plane

Follow these steps on the TSE Management Plane cluster.

1. Create a Service Account

   On the Management Plane EKS cluster, create a Service Account for AWS IAM to allow the AWS Controller to read VPC Lattice resources.

   Check that you have correctly set $EKS_CLUSTER_NAME and $REGION, and set $ACCOUNT to your 12-digit account ID:

   SA_NAME=tse-mp-lattice
   
   eksctl create iamserviceaccount \
     --cluster $EKS_CLUSTER_NAME \
     --region $REGION \
     --name ${SA_NAME} \
     --namespace tse \
     --attach-policy-arn arn:aws:iam::${ACCOUNT}:policy/${POLICY_NAME} \
     --approve

2. Enable the AWS Controller

   On the Management Plane cluster, edit the ManagementPlane configuration:

   kubectl edit managementplane managementplane -n tse

   ... and add the following stanza, using appropriate values in the highlighted lines:

   spec:
     providerSettings:
       aws:
         serviceAccountName: tse-mp-lattice
       lattice:
         enabled: true
         regions:
         - eu-west-2
         tenant: tse

   You can verify the installation and inspect the settings:

   kubectl get sa -n tse | grep $SA_NAME
   kubectl get deployments -n tse aws-controller
   kubectl get pods -n tse -l app=aws-controller

   Follow the logs using:

   kubectl logs -f -n tse -l app=aws-controller

You have now configured your TSE Management Plane to run the AWS Controller service. This service periodically polls the Lattice Service Registry to discover services that should be exposed within the TSE EKS Workload clusters.

Expose a Lattice Service

Prerequisites

Before you proceed, you should have:

1. Prepared your TSE Management Plane as described above, and associated the Cluster's VPC with a Lattice Service Network
2. Associate one or more TSE Workload Cluster VPCs with the Lattice Service Network
3. Deployed a service on the Lattice Service Network and confirmed that it is functioning

If you have a complex configuration, you will also need to create appropriate security groups to allow traffic between the VPCs and the Service Network. This is not necessary for the simple, default configuration.

Prepare the Service

You can use any Lattice-hosted service. Verify that the service is functioning by accessing it using its Lattice-assigned domain name.

Reference: Create an example Lattice Service

The following instructions explain how to create a sample Lattice service on a VM attached to a VPC that is associated with the Lattice Service Network.

Run a simple web server

Get a shell on the VM, and start a simple web server process listening on port 8080 using python3:

cd /tmp
echo "Hello, World!" > index.html
python3 -m http.server 8080 &

This will run the python3 process in the background, sending logs to the current terminal.

Verify that you can access the web server by running the command locally:

curl http://localhost:8080/

Expect to see the output Hello, World!.

Make the Web Server Accessible from outside the VM

Locate the VM instance and edit the Security Group attached to that instance. Add a rule allowing TCP port 8080 from all sources (0.0.0.0/0).

Create a VPC Lattice Target Group for the VM and service

Create a new VPC Lattice Target Group, with the following details:

• Target type: Instances
• Target Group name: select a name, such as helloworld-tg
• Protocol and Port: HTTP, 8080
• VPC: choose the VPC where the VM instance resides
• Enable Health Checks, with the following settings:
  • Health Check Path: /?HealthCheck
  • Advanced health check settings: Health Check Interval: 10 seconds

Register the VM Instance with the VPC Lattice Target Group you are creating.

Create a VPC Lattice Service for the service

Create a new VPC Lattice Target Group using the Target Group you just created:

1. Create a new VPC Lattice Service

   Select Service Name: chose a name, such as helloworld-service

   Don't enable other features, and proceed to 'Review and Create'.

2. Define Routing

   Add a Listener for the Lattice Service:

   • Protocol and Port: HTTP, 80
   • Default Action: forward to the Target Group hellowworld-tg you created above

   Don't enable other features, and proceed to 'Review and Create'.

3. Create network associations

   Select your Lattice Service Network to associate this Lattice Service with the Service Network.

Finally, create your Lattice Service.

Test your Lattice Service

Once the service is created, if you are watching the logs from your python3 web server you should see the health-check requests (GET /?HealthCheck HTTP/1.1) from the Lattice infrastructure. It will take several minutes for the infrastructure to settle, to deploy any necessary proxies, verify the health of your service and make it Active.

Review the service configuration and determine the DNS name that Lattice has assigned to the service:

Review the Lattice Service configuration

Verify that you can access the service using its DNS name by issuing a curl request locally, from the Instance VM:

curl http://helloworld-service-0e6e3c28c5d1e98fb.7d67968.vpc-lattice-svcs.eu-west-2.on.aws/

You now have a working Lattice Service!

Expose the Service to TSE

When you tag the Lattice Service. TSE's AWS Controller will import tagged services into TSE, creating appropriate ServiceEntries so that the service can be consumed from within each EKS cluster.

1. Tag the Lattice Service

   Edit the VPC Lattice Service you wish to expose to TSE:

   Tag the Lattice Service with Tetrate:ExposeToMesh

   Add the following tags:

   • Tetrate:ExposeToMesh: value true to tag this service to be exposed within the TSE-managed mesh
   • Tetrate:Hostnames: (optional) the DNS hostname that will identify the service within the TSE-managed mesh

   TSE's AWS Controller polls the Lattice Service registry, and will create TSE services for each Lattice service that is tagged with the ExposeToMesh key.

2. Determine the Lattice-Generated DNS name

   The TSE management plane makes the remote Lattice service available using three DNS names:

   • The DNS name assigned to the service by Lattice, for example helloworld-service-0e6e3c28c5d1e98fb.7d67968.vpc-lattice-svcs.eu-west-2.on.aws
   • An auto-generated name, TSE-specific name using the awsvpclattice root domain - service-name.servicenetwork-name.awsvpclattice
   • Optional - a name that your specify in the Tetrate:Hostnames field

   It does so by creating a ServiceEntry in the EKS cluster's tetrate-system namespace:

   Output from kubectl get serviceentry -n tetrate-system

   NAME                                               HOSTS                                                                                                                                                                 LOCATION   RESOLUTION   AGE
   td-tetrate-helloworld-service-my-service-network   ["helloworld-service-0e6e3c28c5d1e98fb.7d67968.vpc-lattice-svcs.eu-west-2.on.aws","helloworld-service.my-service-network.awsvpclattice","hello-service.tetrate.io"]              DNS          10m

Testing the Service

Gain a shell on one of the distro-based containers running in your TSE Workload Cluster, where you can run curl from. For example, if the bookinfo app is deployed in your cluster, you can gain a shell on the ratings container:

kubectl exec deploy/ratings-v1 -n bookinfo --stdin --tty -- /bin/bash

You can then invoke the remote service using any of the DNS names in the ServiceEntry:

curl hello-service.tetrate.io