Install on Amazon EKS

Install HAProxy Enterprise Kubernetes Ingress Controller on AWS EKS from AWS

This section describes how to deploy the HAProxy Enterprise Kubernetes Ingress Controller in Amazon Elastic Kubernetes Service (EKS) directly from AWS.

The procedure should take approximately 15 minutes to complete.

Pre-installation checklist Jump to heading

Before getting started:

What you will accomplish Jump to heading

In this guide, you will:

  • Connect to your EKS cluster with the AWS CLI and kubectl
  • Launch the HAProxy Enterprise Kubernetes Ingress Controller with Helm
  • Publish the ingress controller’s service using an EC2 Classic Load Balancer

Create the required IAM role Jump to heading

The following command requires that you have an IAM OpenID Connect (OIDC) provider for your cluster, and eksctl is required.

To determine whether you have one, or to create one, see Creating an IAM OIDC provider for your cluster.

If you need to use a different tool to create the role and annotate the Kubernetes service account, see Configuring a Kubernetes service account to assume an IAM role.

nix
eksctl create iamserviceaccount \
--name [Your ServiceAccount name] --namespace haproxy-controller --cluster [Your cluster name] --role-name [Your role name] \
--role-only --attach-policy-arn arn:aws:iam::aws:policy/service-role/AWSLicenseManagerConsumptionPolicy --approve
nix
eksctl create iamserviceaccount \
--name [Your ServiceAccount name] --namespace haproxy-controller --cluster [Your cluster name] --role-name [Your role name] \
--role-only --attach-policy-arn arn:aws:iam::aws:policy/service-role/AWSLicenseManagerConsumptionPolicy --approve

You can pick your preferred name for the the ServiceAccount created by eksctl.

Subscribe via the AWS Marketplace Jump to heading

Before you can launch the ingress controller, you must subscribe to get a license. To subscribe:

  1. From the AWS Marketplace, choose HAProxy Enterprise Ingress Controller. You can estimate costs by using the pricing table on the marketplace product page.

  2. Click Continue to Subscribe to start a subscription to the HAProxy Enterprise Kubernetes Ingress Controller software.

  3. On the Create an agreement to this software screen, review the subscription terms in the Contract sidebar, then click Create Contract to subscribe to the software.

  4. Under Renewal Settings, choose whether to renew your subscription automatically.

  5. Under Contract Options, set the number of ingress controller instances to deploy. Deploying more than one provides high availability of the service.

  6. Click Continue to Configuration.

  7. On the Configure this software screen, choose the fulfillment option and then software version, which determines the version of the Helm chart you will launch. Newer versions of the Helm chart support newer versions of HAProxy Enterprise Kubernetes Ingress Controller. Typically, you will choose the newest version.

  8. Click Continue to Launch.

  9. On the Launch this software screen, select Amazon managed Kubernetes for the Launch target to use Amazon EKS hosted on AWS.

  10. Optional: If you do not yet have an EKS cluster, choose Launch on a new EKS cluster with QuickLaunch for Launch method, then follow the steps in the section Launch on a new EKS cluster with QuickLaunch.

  11. If you already have an Amazon EKS cluster, choose Launch on an existing cluster.

Launch on a new EKS cluster with QuickLaunch Jump to heading

To launch HAProxy Enterprise Kubernetes Ingress Controller into a new EKS cluster:

  1. On the Launch this software screen, select Launch on a new EKS cluster with QuickLaunch for Launch method.

  2. Click QuickLaunch with CloudFormation.

  3. On the Quick create stack screen, set the following values:

    • Stack name to a name for your CloudFormation stack. For example, example-eks-stack.
    • EKS cluster name to a name for your cluster. For example, example-eks-cluster.
    • Kubernetes service name to a name for the service account. For example, example-eks-serviceaccount.
    • Create service account to true
    • EC2 key pair to an SSH key pair to enable SSH access to the cluster nodes.
  4. Check the boxes to acknowledge the creation of IAM resources, then click Create stack. This will create the Amazon EKS cluster and launch HAProxy Enterprise Kubernetes Ingress Controller into it.

  5. Once the stack has been created, go to the EKS Dashboard and then the Clusters tab to view your cluster.

Launch on an existing cluster Jump to heading

To launch HAProxy Enterprise Kubernetes Ingress Controller into an EKS cluster:

  1. Ensure that your EKS cluster has nodes deployed to it by following the steps in Creating a managed node group.

  2. Create a token from your subscription license. You will use the token when launching the ingress controller with Helm.

    To create a token, go to the AWS License Manager and find the HAProxy Enterprise Ingress Controller license in the list of granted licenses. Then, on the License details tab, create a new token. Afterwards, be sure to download the token details either by clicking Download .csv file or by clicking Show token.

  3. Create an access key for connecting to AWS via the AWS CLI.

    In the AWS Console, expand your account menu, located in the upper right, and select Security Credentials. On the My security credentials page, go to the Access keys section and create a new access key for the CLI if you do not already have one stored. This will give you an Access Key ID and Secret Access key. Store these somewhere so that you have them later.

  4. On your local workstation, configure the AWS CLI to connect to your AWS account by creating a profile via the aws configure command. This will prompt you for your access key and secret access key.

    nix
    aws configure
    nix
    aws configure

    Learn more about profiles.

  5. Connect to your Kubernetes cluster using the AWS CLI. This will create a ~/.kube/config file that contains connection details:

    nix
    aws eks update-kubeconfig \
    --region [Your region] \
    --name [Your cluster name]
    nix
    aws eks update-kubeconfig \
    --region [Your region] \
    --name [Your cluster name]
  6. Check that you can access the cluster by calling kubectl get pods:

    nix
    kubectl get pods
    nix
    kubectl get pods

    If your cluster is new it may not have any resources:

    output
    text
    No resources found in default namespace.
    output
    text
    No resources found in default namespace.
  7. Create the haproxy-controller namespace in your cluster. We will launch all ingress controller resources into this Kubernetes namespace.

    nix
    kubectl create namespace haproxy-controller
    nix
    kubectl create namespace haproxy-controller
  8. From the token you created from your license, copy the token’s value to a variable named LICENSE_TOKEN. Then store it in a Kubernetes secret named license-token-secret.

    nix
    LICENSE_TOKEN="eyJhbGciOiJSUzUxMiIsInR5cCI..."
    kubectl create secret generic license-token-secret --from-literal=license_token=$LICENSE_TOKEN --from-literal=iam_role=arn:aws:iam::123832860963:role/service-role/AWSMarketplaceLicenseTokenConsumptionRole --namespace haproxy-controller
    nix
    LICENSE_TOKEN="eyJhbGciOiJSUzUxMiIsInR5cCI..."
    kubectl create secret generic license-token-secret --from-literal=license_token=$LICENSE_TOKEN --from-literal=iam_role=arn:aws:iam::123832860963:role/service-role/AWSMarketplaceLicenseTokenConsumptionRole --namespace haproxy-controller
  9. Log into the Helm registry using the helm registry login command.

    nix
    aws ecr get-login-password --region us-east-1 | \
    helm registry login \
    --username AWS \
    --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com
    nix
    aws ecr get-login-password --region us-east-1 | \
    helm registry login \
    --username AWS \
    --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com
    output
    text
    Login Succeeded
    output
    text
    Login Succeeded
  10. Use the helm pull command to download the Helm chart. Set version to the Fulfillment options version displayed at the top of the Launch this software screen. It is also displayed in the example helm pull command found on that page. For example, 1.29.3.

    nix
    mkdir chart
    cd chart
    helm pull oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/haproxy-technologies/haproxy-ingress-controller-helm-chart2 \
    --version <VERSION>
    nix
    mkdir chart
    cd chart
    helm pull oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/haproxy-technologies/haproxy-ingress-controller-helm-chart2 \
    --version <VERSION>
  11. Launch the ingress controller. The name of the archived file may be different, depending on the version of the Helm chart you chose for the fulfillment option.

    Helm values file

    The following example uses --set invocations to configure the ingress controller. When installing with Helm, you can instead use a Helm values file to provide your configuration values. Using a Helm values file can provide for better traceability of configuration changes and reduce the complexity of Helm installation commands.

    nix
    helm install haproxy-kubernetes-ingress \
    --namespace haproxy-controller \
    --set controller.service.type=LoadBalancer \
    --set "aws.licenseConfigSecretName=license-token-secret" \
    ./haproxy-ingress-controller-helm-chart2-*.tgz
    nix
    helm install haproxy-kubernetes-ingress \
    --namespace haproxy-controller \
    --set controller.service.type=LoadBalancer \
    --set "aws.licenseConfigSecretName=license-token-secret" \
    ./haproxy-ingress-controller-helm-chart2-*.tgz
    output
    text
    NAME: haproxy-kubernetes-ingress
    LAST DEPLOYED: Fri Mar 24 15:09:05 2023
    NAMESPACE: haproxy-controller
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    HAProxy Kubernetes Ingress Controller has been successfully installed.
    output
    text
    NAME: haproxy-kubernetes-ingress
    LAST DEPLOYED: Fri Mar 24 15:09:05 2023
    NAMESPACE: haproxy-controller
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    HAProxy Kubernetes Ingress Controller has been successfully installed.

    This will create an EC2 Classic Load Balancer that routes traffic to the ingress controller service. You can find its DNS name by going to the EC2 Dashboard and viewing Load Balancing > Load Balancers, then selecting the load balancer.

Launch as an Amazon EKS Add-on using the AWS console Jump to heading

Before getting started, ensure you already have a valid AWS Marketplace Subscription, and access to an Amazon EKS cluster.

After subscribing to HAProxy Enterprise Ingress Controller on AWS Marketplace and following the on-screen instructions successfully, you are redirected to the Amazon EKS console.

Once done, follow the following steps:

  1. Access your EKS cluster.

  2. Click the Add-ons tab and select Get more add-ons to find the HAProxy Enterprise Ingress Controller EKS add-on.

Launch as an Amazon EKS Add-on using the AWS CLI Jump to heading

Prior to the AWS CLI commands, ensure that the target Amazon EKS cluster has been already created.

Once done, on your workstation, run the following command to enable the HAProxy Enterprise Ingress Controller add-on for your Amazon EKS cluster:

nix
aws eks create-addon --cluster-name [Your cluster name] --region [Your region] \
--addon-name haproxy-kubernetes-ingress
nix
aws eks create-addon --cluster-name [Your cluster name] --region [Your region] \
--addon-name haproxy-kubernetes-ingress
output
json
{
"addon": {
"addonName": "haproxy-kubernetes-ingress",
"clusterName": "[Your cluster name]",
"status": "CREATING",
"addonVersion": "v1.97.0-eksbuild.1",
"health": {
"issues": []
},
"addonArn": "arn:aws:eks:$AWS_REGION:xxxxxxxxxxxx:addon/[Your cluster name]/haproxy-kubernetes-ingress/90c23198-cdd3-b295-c410-xxxxxxxxxxxx",
"createdAt": "2022-12-01T12:18:26.497000-08:00",
"modifiedAt": "2022-12-01T12:50:52.222000-08:00",
"tags": {}
}
}
output
json
{
"addon": {
"addonName": "haproxy-kubernetes-ingress",
"clusterName": "[Your cluster name]",
"status": "CREATING",
"addonVersion": "v1.97.0-eksbuild.1",
"health": {
"issues": []
},
"addonArn": "arn:aws:eks:$AWS_REGION:xxxxxxxxxxxx:addon/[Your cluster name]/haproxy-kubernetes-ingress/90c23198-cdd3-b295-c410-xxxxxxxxxxxx",
"createdAt": "2022-12-01T12:18:26.497000-08:00",
"modifiedAt": "2022-12-01T12:50:52.222000-08:00",
"tags": {}
}
}

The HAProxy Ingress Controller add-on should be available in a few minutes. You can check the status by viewing the running pods in your cluster:

nix
kubectl -n haproxy-controller get pods
nix
kubectl -n haproxy-controller get pods

Disable the HAProxy Enterprise Ingress Controller add-on Jump to heading

To disable the add-on, you can run the following command:

nix
aws eks delete-addon --cluster-name $YOUR_CLUSTER_NAME --region $AWS_REGION\
--addon-name haproxy-kubernetes-ingress
nix
aws eks delete-addon --cluster-name $YOUR_CLUSTER_NAME --region $AWS_REGION\
--addon-name haproxy-kubernetes-ingress

Make changes to your AWS Marketplace subscription Jump to heading

To make changes to the renewal settings or number of ingress controller instances:

  1. Visit the HAProxy Enterprise Ingress Controller AWS Marketplace listing.

  2. Click View subscription.

  3. In the Actions menu, choose View terms.

  4. Make changes, then click Modify contract.

Do you have any suggestions on how we can improve the content of this page?