github.com/projectcontour/contour@v1.28.2/site/content/docs/1.25/guides/deploy-aws-tls-nlb.md (about)

     1  ---
     2  title: AWS Network Load Balancer TLS Termination with Contour
     3  ---
     4  
     5  ## Motivation
     6  
     7  ![diagram illustrating connection between network load balancer and contour](/img/aws-nlb-tls/fig.jpg){:class="img-fluid"}
     8  
     9  Managing TLS certificates (and related configuration) for production cluster workloads is both time consuming, and high risk. For example, storing multiple copies of a certificate secret key in the cluster may increases the chances of it being compromised. Additionally, TLS can be complicated to configure and implement properly. 
    10  
    11  Traditionally, TLS termination at the load balancer step required using more expensive application load balancers (ALBs). AWS introduced TLS termination for network load balancers (NLBs) for enhanced security and cost effectiveness. 
    12  
    13  The TLS implementation used by the AWS NLB is formally verified and maintained. Additionally, AWS Certificate Manager (ACM) is used, fully isolating your cluster from access to the private key. 
    14  
    15  ## Solution Overview
    16  
    17  An external client transmits a request to the NLB. The request is encrypted with TLS using the production (e.g., client facing) certificate, and on port 443. 
    18  
    19  The NLB decrypts the request, and transmits it on to Envoy running in your cluster on port 8080. It follows the standard request routing configured within the cluster. Notably, the request received within the cluster includes the actual origin IP address of the external client. 
    20  
    21  Alternate ports may be configured. End-to-end encryption technically requires the segment between the NLB and cluster pods be encrypted also. A follow-up post will describe the NLB originating TLS based on a cluster certificate. 
    22  
    23  ## Steps
    24  
    25  ### Prerequisites
    26  
    27  1. Access to DNS records for domain name.
    28  
    29  [Review the docs on registering domains with AWS's Route 53.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html)
    30  
    31  An alternate DNS provider may be used, such as Google Domains or Namecheap.
    32  
    33  Later, a subdomain (e.g., demo-service.gcline.us) will be created, pointing to the NLB. Additionally, access to the DNS records is required to generate a TLS certificate for use by the NLB. 
    34  
    35  3. Verify [Contour is installed in the cluster.](https://projectcontour.io/getting-started/)
    36  
    37  4. Install [AWS Load Balancer Controller.]( https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/deploy/installation/)
    38  
    39  Generally, setting up the Load Balancer Controller has two steps: enabling IAM roles for service accounts, and adding the controller to the cluster. The IAM role allows the controller in the Kubernetes cluster to manage AWS resources. [Learn more about IAM roles for service accounts.](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
    40  
    41  ### Configure
    42  
    43  1. Generate TLS Certificate
    44  
    45  Create a public TLS certificate for the domain using AWS Certificate Manager (ACM). This is streamlined when the domain is managed by Route 53. Review the [AWS Certificate Manager Docs.](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html#request-public-console)
    46  
    47  The domain name on the TLS certificate must correspond to the planned domain name for the kubernetes service. The domain name may be specified explicitly (e.g., tls-demo.gcline.us), or a wildcard certificate can be used (e.g., *.gcline.us).
    48  
    49  If the domain is registered with Route53, the TLS certificate request will automatically be approved. Otherwise, follow ACM console the instructions to create a DNS record to validate the domain. 
    50  
    51  After validation, the certificate will be available for use in your AWS account. 
    52  
    53  Note the ARN of the certificate, which uniquely identifies it in kubernetes config files. 
    54  
    55  ![screenshot indicating location of ARN value in web console](/img/aws-nlb-tls/acm-arn.png){:class="img-fluid"}
    56  
    57  2. Create Envoy Service with new NLB
    58  
    59  Contour expects a kubernetes service pointing to Envoy. Add annotations to the service to enable NLB TLS termination, before the traffic reaches Envoy. The annotations are actioned by the load balancer controller. [Review all the NLB annotations on GitHub.](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/guide/service/annotations/)
    60  
    61  | annotation name | value | meaning | 
    62  | ----- | --- | ----- |
    63  | service.beta.kubernetes.io/aws-load-balancer-type | external | explicitly requires an NLB, instead of an ALB |
    64  | service.beta.kubernetes.io/aws-load-balancer-nlb-target-type | ip | route traffic directly to the pod IP |
    65  | service.beta.kubernetes.io/aws-load-balancer-scheme | internet-facing | An internet-facing load balancer has a publicly resolvable DNS name |
    66  | service.beta.kubernetes.io/aws-load-balancer-ssl-cert | "arn:aws:acm:..." | identifies the TLS certificate used by the NLB |
    67  | service.beta.kubernetes.io/aws-load-balancer-ssl-ports | 443 | determines the port the NLB should listen for TLS traffic on| 
    68  
    69  Example: 
    70  
    71  ```
    72  apiVersion: v1
    73  kind: Service
    74  metadata:
    75    name: envoy
    76    namespace: projectcontour
    77    annotations:
    78      service.beta.kubernetes.io/aws-load-balancer-type: external
    79      service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
    80      service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
    81      service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:us-east-2:185309785115:certificate/7610ed7d-5a81-4ea2-a18a-7ba1606cca3e"
    82      service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
    83  spec:
    84    externalTrafficPolicy: Local
    85    ports:
    86    - port: 443
    87      targetPort: 8080
    88      name: http
    89      protocol: TCP
    90    selector:
    91      app: envoy
    92    type: LoadBalancer
    93  ```
    94  
    95  *Note:* Don't modify an existing service to add NLB TLS termination. This may result in unexpected behavior, such as duplicate NLB resources or incorrect NLB configuration. 
    96  
    97  3. Configure DNS
    98  
    99  **Get domain name using kubectl.** 
   100  
   101  The service name and namespace were defined above.
   102  
   103  ```
   104  kubectl get svc envoy --namespace projectcontour
   105  ```
   106  
   107  ```
   108  NAME    TYPE           CLUSTER-IP      EXTERNAL-IP                                                                     PORT(S)        AGE
   109  envoy   LoadBalancer   10.100.24.154   a7ea2bbde8a164036a7e4c1ed5700cdf-154fb911d990bb1f.elb.us-east-2.amazonaws.com   443:31606/TCP   40d
   110  ```
   111  
   112  Note the last 4 digits of the domain name for the NLB. For example, "bb1f". 
   113  
   114  **Setup DNS alias for NLB**
   115  
   116  Create a DNS record pointing from a friendly name (e.g., tls-demo.gcline.us) to the NLB domain (e.g., bb1f.elb.us-east-2.amazonaws.com). 
   117  
   118  For AWS's Route 53, follow the instructions below. If you use a different DNS provider, follow their instructions for [creating a CNAME record](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/#cname-records). 
   119  
   120  First, create a new record in Route 53. 
   121  
   122  Use the "A" record type, and enable the ["alias" option.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-alias.html) This option attaches the DNS record to the AWS resource, without requiring an extra lookup step for clients. 
   123  
   124  Select the NLB resource. Double check the region, and use the last 4 digits (noted earlier) to select the proper resource. 
   125  
   126  ![screenshot of Route 53 New Record Console](/img/aws-nlb-tls/record.png){:class="img-fluid"}
   127  
   128  ### Verify
   129  
   130  Attempt to access the NLB domain at port 443 with HTTPS/TLS. Is the connection successful? What certificate is used? Does it reach the expected endpoint within the cluster? 
   131  
   132  ### Next Steps
   133  
   134  Create a second TLS certificate within the cluster, for securing connections between the NLB and pods. A guide on this topic is forthcoming.
   135