docs-source/docs/modules/deployment/pages/aws-ingress.adoc

= AWS LoadBalancer Controller
:page-toclevels: 3

include::partial$include.adoc[]

To expose your application's gRPC or HTTPS endpoints publicly to the internet you can use the https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/[AWS Load Balancer Controller {tab-icon}, window="tab"] with a https://kubernetes.io/docs/concepts/services-networking/ingress/[Kubernetes Ingress {tab-icon}, window="tab"] created by the Akka Operator. This is useful when external services, or clients beyond the EKS cluster need to consume the gRPC or HTTPS endpoints.

== Install the LoadBalancer Controller

Follow the instructions in the https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html[AWS Load Balancer Controller installation documentation {tab-icon}, window="tab"]. Additional information and resources can be found in the https://github.com/aws/eks-charts/tree/master/stable/aws-load-balancer-controller[AWS Load Balancer Controller Helm chart for Kubernetes Github Repo {tab-icon}, window="tab"]

[#_tls_certificate]
== TLS certificate

A Transport Layer Security (TLS) certificate provides privacy and data integrity between two or more communicating applications. You will need a TLS certificate for the internet facing load balancer. The Akka Cloud Platform does not manage or create TLS certificates.

When you want to expose an Akka gRPC service through a Load balancer, you will have to provide a TLS certificate. Request or import a certificate using the https://console.aws.amazon.com/acm/home[Amazon Certificate Manager (ACM) console {tab-icon}, window="tab"]. While in the ACM console, you will need to select the region you are working in. You will need to provide the Amazon Resource Name (ARN) of the certificate as you create the Akka Microservice Custom Resource.

Alternatively, for development and testing, you can create your own self-signed certificate and then import it.
You can find additional details regarding self-singed certificates and AWS at https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_server-certs.html[Managing server certificates in IAM {tab-icon}, window="tab"] and https://docs.aws.amazon.com/acm/latest/userguide/import-certificate-prerequisites.html[Prerequisites for Importing Certificates {tab-icon}, window="tab"]

A self-singed certificate can be created as in the following example:

[source,shell script]
----
openssl req -new \
    -newkey rsa:2048 -x509 -sha256 -days 365 \
    -nodes \
    -out MyCertificate.crt \
    -keyout MyKey.key \
    -subj "/CN=example.com/O=example"
----

NOTE: When creating a self-signed certificate, make sure you use a domain name for the 'Common Name', for instance, "example.com". If you do not use a domain name, but just any non-empty name for the 'Common Name', the ingress controller will not be able to find the certificate and the ingress will fail to get an IP address, which shows up as a `CertificateNotFound` error in the events for the ingress.

You can import the cert with the following command:

[source,shell script]
----
aws iam upload-server-certificate \
    --server-certificate-name MyCertificate \
    --certificate-body file://MyCertificate.crt \
    --certificate-chain file://MyCertificate.crt \
    --private-key file://MyKey.key
----

When the preceding command is successful, it returns metadata about the uploaded certificate, including its Amazon Resource Name (ARN). 

Make a note of the policy ARN for the next step.

You can verify of the certificate was imported successfully by listing the certificates with the following command:

[source,shell script]
----
aws iam list-server-certificates
----

The Akka Cloud Platform operator will create the Kubernetes `Ingress` which references your TLS certificate with an https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[Amazon Resource Name (ARN) {tab-icon}, window="tab"]

However, please remember that the operator is not involved in any other part of the process for TLS certification management, including renewals.

== Enable grpcIngress

Add the `grpcIngress` section to the deployment descriptor and set its class to `alb`:

.kubernetes/shopping-cart-service-cr.yml:
[source,yaml]
----
apiVersion: pekko.apache.org/v1
kind: PekkoMicroservice
metadata:
  name: shopping-cart-service
  namespace: "shopping"
spec:
  image: <image>
  grpcIngress:
    enabled: true
    certificate: <certificate_arn>
    class: "alb"
----

Replace the certificate `arn` with the one from the previous step.

When the deployment descriptor has been applied, the Akka Operator will create an Ingress with the appropriate ALB annotations and `NodePort` service.
You can retrieve the public address with:

[source,shell script]
----
kubectl get ingress shopping-order-service-grpc-ingress --namespace=shopping
----

To access the public endpoint with grpcurl you use the public address from above, with port 443:

[source,shell script]
----
grpcurl -insecure \
    -d '{"cartId":"cart3", "itemId":"hoodie", "quantity":2}' \
    k8s-shopping-shopping-18efcf54bb-2096059642.eu-central-1.elb.amazonaws.com:443 \
    shoppingcart.ShoppingCartService.AddItem
----

NOTE: You have to use the `-insecure` flag if the certificate is self-signed.

Replace the host name (`k8s-shopping-shopping-18efcf54bb-2096059642.eu-central-1.elb.amazonaws.com`) with your actual host name.