Ingress tutorials
Load balance TCP services
The HAProxy Kubernetes Ingress Controller can load balance TCP services. It accomplishes this using a ConfigMap to define its TCP services.
Load balance TCP services Jump to heading
To configure the HAProxy Kubernetes Ingress Controller for load balancing TCP services, we will create a YAML file that contains a ConfigMap definition. We will name the file tcp-configmap.yaml
.
-
In this example, we set the ConfigMap’s
name
totcp-configmap
, but you can use any name. In thedata
section, add the ports that you will open on the ingress controller for receiving traffic, mapped to their associated backend services.tcp-configmap.yamlyamlapiVersion: v1kind: ConfigMapmetadata:name: tcp-configmapnamespace: haproxy-controllerdata:2000:default/example-service1:30002001:mynamespace/example-service2:3001tcp-configmap.yamlyamlapiVersion: v1kind: ConfigMapmetadata:name: tcp-configmapnamespace: haproxy-controllerdata:2000:default/example-service1:30002001:mynamespace/example-service2:3001 -
Define your backend services as follows:
- The service’s
name
should match the ConfigMap. For example,example-service1
. - The
protocol
should beTCP
. - The
port
should match the ConfigMap. For example,3000
. - The
targetPort
is your container port.
yamlapiVersion: v1kind: Servicemetadata:name: example-service1namespace: defaultspec:selector:app: example-service1ports:- protocol: TCP- port: 3000- targetPort: 3000---apiVersion: v1kind: Servicemetadata:name: example-service2namespace: mynamespacespec:selector:app: example-service2ports:- protocol: TCP- port: 3001- targetPort: 3001yamlapiVersion: v1kind: Servicemetadata:name: example-service1namespace: defaultspec:selector:app: example-service1ports:- protocol: TCP- port: 3000- targetPort: 3000---apiVersion: v1kind: Servicemetadata:name: example-service2namespace: mynamespacespec:selector:app: example-service2ports:- protocol: TCP- port: 3001- targetPort: 3001 - The service’s
-
Apply the ConfigMap and service(s) using
kubectl apply -f
.Example:
nixkubectl apply -f tcp-configmap.yamlnixkubectl apply -f tcp-configmap.yamloutputconfigmap/tcp-configmap created
outputconfigmap/tcp-configmap created
-
Following the creation of your ConfigMap and service(s), you must edit the
haproxy-kubernetes-ingress
deployment and thehaproxy-kubernetes-ingress
service to configure the ingress controller to make connection to your service(s). Depending on whether you installed the ingress controller with Helm or Kubectl, you can edit these resources as follows:We will use the
helm upgrade
command to automatically update thehaproxy-kubernetes-ingress
deployment and service. We will provide a values file to the command using the-f
option. This values file will specify an additional argument for the ingress controller deployment and it will configure our ports.-
Create a file named
myvals.yaml
and add the following:myvals.yamlyamlcontroller:name: controllerservice:tcpPorts:- name: service-1port: 2000targetPort: 2000nodePort: 30000protocol: TCP- name: service-2port: 2001targetPort: 2001nodePort: 30001protocol: TCPextraArgs:- --configmap-tcp-services=haproxy-controller/tcp-configmapmyvals.yamlyamlcontroller:name: controllerservice:tcpPorts:- name: service-1port: 2000targetPort: 2000nodePort: 30000protocol: TCP- name: service-2port: 2001targetPort: 2001nodePort: 30001protocol: TCPextraArgs:- --configmap-tcp-services=haproxy-controller/tcp-configmap- For each TCP service, add an entry in
tcpPorts
.- Provide a name for the port. The name of the port cannot exceed 11 characters.
port
is the port the ingress controller service will listen on.targetPort
is the port you defined in the ConfigMap.- Specify a
nodePort
. Valid NodePorts are in the 30000-32767 range. - Set
protocol
toTCP
.
- Add the
--configmap-tcp-services
toextraArgs
and set it to the name of your ConfigMap (haproxy-controller/tcp-configmap
in this example).
- For each TCP service, add an entry in
-
Execute the
helm upgrade
command, providing the name of the YAML values file with-f
:nixhelm upgrade haproxy-kubernetes-ingress -f myvals.yaml haproxytech/kubernetes-ingress \--namespace haproxy-controllernixhelm upgrade haproxy-kubernetes-ingress -f myvals.yaml haproxytech/kubernetes-ingress \--namespace haproxy-controlleroutputRelease "haproxy-kubernetes-ingress" has been upgraded. Happy Helming! NAME: haproxy-kubernetes-ingress [...] Service ports mapped are: - name: http containerPort: 8080 protocol: TCP - name: https containerPort: 8443 protocol: TCP - name: stat containerPort: 1024 protocol: TCP - name: quic containerPort: 8443 protocol: UDP - name: service-1-tcp containerPort: 2000 protocol: TCP - name: service-2-tcp containerPort: 2001 protocol: TCP
outputRelease "haproxy-kubernetes-ingress" has been upgraded. Happy Helming! NAME: haproxy-kubernetes-ingress [...] Service ports mapped are: - name: http containerPort: 8080 protocol: TCP - name: https containerPort: 8443 protocol: TCP - name: stat containerPort: 1024 protocol: TCP - name: quic containerPort: 8443 protocol: UDP - name: service-1-tcp containerPort: 2000 protocol: TCP - name: service-2-tcp containerPort: 2001 protocol: TCP
The
tcpPorts
we specified in the YAMLmyvals.yaml
file are present in the output above. Note that to the ingress controller, the names of our ports have changed and have-tcp
appended to the end of their names. This does not affect operation.
-
To view/edit the
haproxy-kubernetes-ingress
deployment, callkubectl edit deployment
. The command will open the deployment file in your configured editor:nixkubectl -n haproxy-controller edit deployment haproxy-kubernetes-ingressnixkubectl -n haproxy-controller edit deployment haproxy-kubernetes-ingress-
Add the
--configmap-tcp-services
argument inargs
and set the value to the name of your ConfigMap (haproxy-controller/tcp-configmap
in this example).yamlspec:containers:- args:- --default-ssl-certificate=haproxy-controller/kubernetes-ingress-default-cert- --configmap=haproxy-controller/kubernetes-ingress- --http-bind-port=8080- --https-bind-port=8443- --ingress.class=haproxy- --publish-service=haproxy-controller/kubernetes-ingress- --log=info- --configmap-tcp-services=haproxy-controller/tcp-configmap[...]yamlspec:containers:- args:- --default-ssl-certificate=haproxy-controller/kubernetes-ingress-default-cert- --configmap=haproxy-controller/kubernetes-ingress- --http-bind-port=8080- --https-bind-port=8443- --ingress.class=haproxy- --publish-service=haproxy-controller/kubernetes-ingress- --log=info- --configmap-tcp-services=haproxy-controller/tcp-configmap[...] -
Save the changes and close the file. The display shows that the file was edited:
outputdeployment.apps/haproxy-kubernetes-ingress edited
outputdeployment.apps/haproxy-kubernetes-ingress edited
-
-
To view/edit the
haproxy-kubernetes-ingress
service, callkubectl edit service
. The command will open the service file in your configured editor:nixkubectl -n haproxy-controller edit svc haproxy-kubernetes-ingressnixkubectl -n haproxy-controller edit svc haproxy-kubernetes-ingress-
For each TCP service, add an entry in the
ports
section with the following:- Name the port. For example,
example-service1
. - Specify a
nodePort
. Valid NodePorts are in the 30000-32767 range. - Set the
port
to the port the ingress controller service will listen on. For example,2000
. - Set the
protocol
toTCP
. - Set the
targetPort
to the port you defined in the ConfigMap. For example,2000
.
yamlspec:[...]ports:[...]- name: example-service1nodePort: 30000port: 2000protocol: TCPtargetPort: 2000- name: example-service2nodePort: 30001port: 2001protocol: TCPtargetPort: 2001yamlspec:[...]ports:[...]- name: example-service1nodePort: 30000port: 2000protocol: TCPtargetPort: 2000- name: example-service2nodePort: 30001port: 2001protocol: TCPtargetPort: 2001 - Name the port. For example,
-
Save the changes and close the file. The display shows that the file was edited:
outputservice/haproxy-kubernetes-ingress edited
outputservice/haproxy-kubernetes-ingress edited
-
You can define your default editor by using the
KUBE_EDITOR
orEDITOR
environment variables or, if neither are defined,vi
is used for Linux ornotepad
for Windows. -
You can connect to your TCP service through the load balancer on the port you specify as the nodePort
.
TCP load balancing example #1 Jump to heading
In the following example, we will deploy a Pod running BusyBox and we will configure the ingress controller for load balancing traffic to it over TCP. BusyBox provides several Linux utilities and is useful for troubleshooting and testing. We will use an instance of BusyBox to run netcat (nc
) which will listen for the incoming traffic.
Deploy resources Jump to heading
-
To deploy an instance of BusyBox in your Kubernetes cluster, copy the following YAML and save it to a file named
busybox.yaml
:busybox.yamlyamlapiVersion: apps/v1kind: Deploymentmetadata:name: busybox-deploymentlabels:app: busyboxspec:replicas: 1selector:matchLabels:app: busyboxtemplate:metadata:labels:app: busyboxspec:containers:- name: busyboximage: busyboxcommand: ["sh", "-c", "while true; do nc -lk -p 5570; done"]ports:- containerPort: 5570protocol: TCP---apiVersion: v1kind: Servicemetadata:name: busybox-servicespec:selector:app: busyboxports:- protocol: TCPport: 5570targetPort: 5570---apiVersion: v1kind: ConfigMapmetadata:name: tcp-configmapnamespace: haproxy-controllerdata:1980:default/busybox-service:5570busybox.yamlyamlapiVersion: apps/v1kind: Deploymentmetadata:name: busybox-deploymentlabels:app: busyboxspec:replicas: 1selector:matchLabels:app: busyboxtemplate:metadata:labels:app: busyboxspec:containers:- name: busyboximage: busyboxcommand: ["sh", "-c", "while true; do nc -lk -p 5570; done"]ports:- containerPort: 5570protocol: TCP---apiVersion: v1kind: Servicemetadata:name: busybox-servicespec:selector:app: busyboxports:- protocol: TCPport: 5570targetPort: 5570---apiVersion: v1kind: ConfigMapmetadata:name: tcp-configmapnamespace: haproxy-controllerdata:1980:default/busybox-service:5570This YAML contains the definitions for:
- A Deployment for BusyBox named
busybox-deployment
. We specify that we want to use the busybox image.- We specify a
containerPort
of5570
. We will run netcat on this port and connect to it through the load balancer. - The deployment includes a command that will run netcat (
nc
) listening on TCP port5570
.
- We specify a
- A Service named
busybox-service
that will expose port5570
. Note that in the next steps, we will configure the ingress controller to connect to this port. - A ConfigMap named
tcp-configmap
. This provides the ingress controller with connection information. Note that this ConfigMap belongs to thehaproxy-controller
namespace (the namespace created when you installed the ingress controller), whereas the other BusyBox components belong to thedefault
namespace. This ConfigMap specifies that the ingress controller will make connection to the service namedbusybox-service
on port5570
. We will map port1980
to a NodePort in ourhaproxy-kubernetes-ingress
service.
- A Deployment for BusyBox named
-
Apply the changes to create the resources:
nixkubectl apply -f busybox.yamlnixkubectl apply -f busybox.yamloutputdeployment.apps/busybox-deployment created service/busybox-service created configmap/tcp-configmap created
outputdeployment.apps/busybox-deployment created service/busybox-service created configmap/tcp-configmap created
Next we will configure the HAProxy Kubernetes Ingress Controller for load balancing traffic over TCP to our BusyBox instance running netcat.
Configure HAProxy Kubernetes Ingress Controller Jump to heading
To configure the ingress controller for load balancing TCP traffic to our BusyBox instance running netcat:
-
Edit the
haproxy-kubernetes-ingress
deployment and thehaproxy-kubernetes-ingress
service to configure the ingress controller to make connection to the Service namedbusybox-service
on port5570
. Depending on whether you installed the ingress controller with Helm or Kubectl, you can edit these resources as follows:We will use the
helm upgrade
command to automatically update thehaproxy-kubernetes-ingress
deployment and service. We will provide a values file to the command using the-f
option. This values file will specify an additional argument for the ingress controller deployment and it will configure our ports.-
Create a file named
myvals.yaml
and add the following:myvals.yamlyamlcontroller:name: controllerservice:tcpPorts:- name: busyboxport: 1980targetPort: 1980nodePort: 30670protocol: TCPextraArgs:- --configmap-tcp-services=haproxy-controller/tcp-configmapmyvals.yamlyamlcontroller:name: controllerservice:tcpPorts:- name: busyboxport: 1980targetPort: 1980nodePort: 30670protocol: TCPextraArgs:- --configmap-tcp-services=haproxy-controller/tcp-configmap -
Execute the
helm upgrade
command, providing the name of the YAML values file with-f
:nixhelm upgrade haproxy-kubernetes-ingress -f myvals.yaml haproxytech/kubernetes-ingress \--namespace haproxy-controllernixhelm upgrade haproxy-kubernetes-ingress -f myvals.yaml haproxytech/kubernetes-ingress \--namespace haproxy-controlleroutputRelease "haproxy-kubernetes-ingress" has been upgraded. Happy Helming! NAME: haproxy-kubernetes-ingress [...] Service ports mapped are: - name: http containerPort: 8080 protocol: TCP - name: https containerPort: 8443 protocol: TCP - name: stat containerPort: 1024 protocol: TCP - name: quic containerPort: 8443 protocol: UDP - name: busybox-tcp containerPort: 1980 protocol: TCP
outputRelease "haproxy-kubernetes-ingress" has been upgraded. Happy Helming! NAME: haproxy-kubernetes-ingress [...] Service ports mapped are: - name: http containerPort: 8080 protocol: TCP - name: https containerPort: 8443 protocol: TCP - name: stat containerPort: 1024 protocol: TCP - name: quic containerPort: 8443 protocol: UDP - name: busybox-tcp containerPort: 1980 protocol: TCP
-
To view/edit the
haproxy-kubernetes-ingress
deployment, callkubectl edit deployment
. The command will open the deployment file in your configured editor:nixkubectl -n haproxy-controller edit deployment haproxy-kubernetes-ingressnixkubectl -n haproxy-controller edit deployment haproxy-kubernetes-ingress-
Add the
--configmap-tcp-services
argument inargs
and set the value to the name of your ConfigMap (haproxy-controller/tcp-configmap
).yamlspec:containers:- args:- --default-ssl-certificate=haproxy-controller/kubernetes-ingress-default-cert- --configmap=haproxy-controller/kubernetes-ingress- --http-bind-port=8080- --https-bind-port=8443- --ingress.class=haproxy- --publish-service=haproxy-controller/kubernetes-ingress- --log=info- --configmap-tcp-services=haproxy-controller/tcp-configmap[...]yamlspec:containers:- args:- --default-ssl-certificate=haproxy-controller/kubernetes-ingress-default-cert- --configmap=haproxy-controller/kubernetes-ingress- --http-bind-port=8080- --https-bind-port=8443- --ingress.class=haproxy- --publish-service=haproxy-controller/kubernetes-ingress- --log=info- --configmap-tcp-services=haproxy-controller/tcp-configmap[...] -
Save the changes and close the file. The display shows that the file was edited:
outputdeployment.apps/haproxy-kubernetes-ingress edited
outputdeployment.apps/haproxy-kubernetes-ingress edited
-
-
To view/edit the
haproxy-kubernetes-ingress
service, callkubectl edit service
. The command will open the service file in your configured editor:nixkubectl -n haproxy-controller edit svc haproxy-kubernetes-ingressnixkubectl -n haproxy-controller edit svc haproxy-kubernetes-ingress-
Add an entry in the
ports
section with the following:yaml- name: busyboxport: 1980targetPort: 1980nodePort: 30670protocol: TCPyaml- name: busyboxport: 1980targetPort: 1980nodePort: 30670protocol: TCP -
Save the changes and close the file. The display shows that the file was edited:
outputservice/haproxy-kubernetes-ingress edited
outputservice/haproxy-kubernetes-ingress edited
-
You can define your default editor by using the
KUBE_EDITOR
orEDITOR
environment variables or, if neither are defined,vi
is used for Linux ornotepad
for Windows. -
Test the connection through the load balancer (click to expand)
To test the connection to the BusyBox instance running netcat through the load balancer:
-
Get the name of the BusyBox pod by calling
kubectl get pod
:nixkubectl get podnixkubectl get podExample outputNAME READY STATUS RESTARTS AGE busybox-deployment-6fbb645fd4-cfkwp 1/1 Running 0 12m
Example outputNAME READY STATUS RESTARTS AGE busybox-deployment-6fbb645fd4-cfkwp 1/1 Running 0 12m
-
Create a file named
test_message.txt
with the following text:textTest messagetextTest message -
From a server that has connection to your cluster, such as the server from which you run
kubectl
, use netcat to send the test message to the port you specified as the NodePort for your TCP service when you configured the ingress controller. In this example, the NodePort we specified was30670
.nixnc 127.0.0.1 30670 < test_message.txtnixnc 127.0.0.1 30670 < test_message.txtThere will be no output from this command.
-
Check the logs of the BusyBox pod to confirm receipt of the message:
nixkubectl logs busybox-deployment-6fbb645fd4-cfkwpnixkubectl logs busybox-deployment-6fbb645fd4-cfkwpoutputTest Message
outputTest Message
TCP load balancing example #2 Jump to heading
In the following example, we will load balance traffic to an external endpoint at ifconfig.info. This service displays your IP address.
Deploy resources Jump to heading
We will create a Service and then map an Endpoint to it at port 80
.
-
Copy the following YAML and save it to a file named
ifconfig.yaml
:ifconfig.yamlyamlapiVersion: v1kind: Servicemetadata:name: ifcservicespec:ports:- port: 80protocol: TCPname: http---apiVersion: v1kind: Endpointsmetadata:name: ifcservicesubsets:- addresses:- ip: 104.21.4.246ports:- port: 80protocol: TCPname: http---apiVersion: v1kind: ConfigMapmetadata:name: tcp-configmapnamespace: haproxy-controllerdata:1981:default/ifcservice:80ifconfig.yamlyamlapiVersion: v1kind: Servicemetadata:name: ifcservicespec:ports:- port: 80protocol: TCPname: http---apiVersion: v1kind: Endpointsmetadata:name: ifcservicesubsets:- addresses:- ip: 104.21.4.246ports:- port: 80protocol: TCPname: http---apiVersion: v1kind: ConfigMapmetadata:name: tcp-configmapnamespace: haproxy-controllerdata:1981:default/ifcservice:80This YAML contains the definitions for:
- A Service named
ifcservice
that will expose port80
. Note that in the next steps, we will configure the ingress controller to connect to this port. - An Endpoint mapped to
ifcservice
. Note that this Endpoint must have the same name as the Service. - A ConfigMap named
tcp-configmap
. This provides the ingress controller with connection information. Note that this ConfigMap belongs to thehaproxy-controller
namespace (the namespace created when you installed the ingress controller), whereas the other components belong to thedefault
namespace. This ConfigMap specifies that the ingress controller will make connection to the service namedifcservice
on port80
. We will map port1981
to a NodePort in ourhaproxy-kubernetes-ingress
service.
- A Service named
-
Apply the changes to create the resources:
nixkubectl apply -f busybox.yamlnixkubectl apply -f busybox.yamloutputservice/ifcservice created endpoints/ifcservice created configmap/tcp-configmap created
outputservice/ifcservice created endpoints/ifcservice created configmap/tcp-configmap created
Next we will configure the HAProxy Kubernetes Ingress Controller for load balancing traffic over TCP to the Endpoint.
Configure HAProxy Kubernetes Ingress Controller Jump to heading
To configure the ingress controller for load balancing TCP traffic to the external Endpoint:
-
Edit the
haproxy-kubernetes-ingress
deployment and thehaproxy-kubernetes-ingress
service to configure the ingress controller to make connection to the Service namedifcservice
on port80
. Depending on whether you installed the ingress controller with Helm or Kubectl, you can edit these resources as follows:We will use the
helm upgrade
command to automatically update thehaproxy-kubernetes-ingress
deployment and service. We will provide a values file to the command using the-f
option. This values file will specify an additional argument for the ingress controller deployment and it will configure our ports.-
Create a file named
myvals.yaml
and add the following:myvals.yamlyamlcontroller:name: controllerservice:tcpPorts:- name: ifconnport: 1981targetPort: 1981nodePort: 30681protocol: TCPextraArgs:- --configmap-tcp-services=haproxy-controller/tcp-configmapmyvals.yamlyamlcontroller:name: controllerservice:tcpPorts:- name: ifconnport: 1981targetPort: 1981nodePort: 30681protocol: TCPextraArgs:- --configmap-tcp-services=haproxy-controller/tcp-configmap -
Execute the
helm upgrade
command, providing the name of the YAML values file with-f
:nixhelm upgrade haproxy-kubernetes-ingress -f myvals.yaml haproxytech/kubernetes-ingress \--namespace haproxy-controllernixhelm upgrade haproxy-kubernetes-ingress -f myvals.yaml haproxytech/kubernetes-ingress \--namespace haproxy-controlleroutputRelease "haproxy-kubernetes-ingress" has been upgraded. Happy Helming! NAME: haproxy-kubernetes-ingress [...] Service ports mapped are: - name: http containerPort: 8080 protocol: TCP - name: https containerPort: 8443 protocol: TCP - name: stat containerPort: 1024 protocol: TCP - name: quic containerPort: 8443 protocol: UDP - name: ifconn-tcp containerPort: 1981 protocol: TCP
outputRelease "haproxy-kubernetes-ingress" has been upgraded. Happy Helming! NAME: haproxy-kubernetes-ingress [...] Service ports mapped are: - name: http containerPort: 8080 protocol: TCP - name: https containerPort: 8443 protocol: TCP - name: stat containerPort: 1024 protocol: TCP - name: quic containerPort: 8443 protocol: UDP - name: ifconn-tcp containerPort: 1981 protocol: TCP
-
To view/edit the
haproxy-kubernetes-ingress
deployment, callkubectl edit deployment
. The command will open the deployment file in your configured editor:nixkubectl -n haproxy-controller edit deployment haproxy-kubernetes-ingressnixkubectl -n haproxy-controller edit deployment haproxy-kubernetes-ingress-
Add the
--configmap-tcp-services
argument inargs
and set the value to the name of your ConfigMap (haproxy-controller/tcp-configmap
).yamlspec:containers:- args:- --default-ssl-certificate=haproxy-controller/kubernetes-ingress-default-cert- --configmap=haproxy-controller/kubernetes-ingress- --http-bind-port=8080- --https-bind-port=8443- --ingress.class=haproxy- --publish-service=haproxy-controller/kubernetes-ingress- --log=info- --configmap-tcp-services=haproxy-controller/tcp-configmap[...]yamlspec:containers:- args:- --default-ssl-certificate=haproxy-controller/kubernetes-ingress-default-cert- --configmap=haproxy-controller/kubernetes-ingress- --http-bind-port=8080- --https-bind-port=8443- --ingress.class=haproxy- --publish-service=haproxy-controller/kubernetes-ingress- --log=info- --configmap-tcp-services=haproxy-controller/tcp-configmap[...] -
Save the changes and close the file. The display shows that the file was edited:
outputdeployment.apps/haproxy-kubernetes-ingress edited
outputdeployment.apps/haproxy-kubernetes-ingress edited
-
-
To view/edit the
haproxy-kubernetes-ingress
service, callkubectl edit service
. The command will open the service file in your configured editor:nixkubectl -n haproxy-controller edit svc haproxy-kubernetes-ingressnixkubectl -n haproxy-controller edit svc haproxy-kubernetes-ingress-
Add an entry in the
ports
section with the following:yaml- name: busyboxport: 1981targetPort: 1981nodePort: 30681protocol: TCPyaml- name: busyboxport: 1981targetPort: 1981nodePort: 30681protocol: TCP -
Save the changes and close the file. The display shows that the file was edited:
outputservice/haproxy-kubernetes-ingress edited
outputservice/haproxy-kubernetes-ingress edited
-
You can define your default editor by using the
KUBE_EDITOR
orEDITOR
environment variables or, if neither are defined,vi
is used for Linux ornotepad
for Windows. -
Test the connection through the load balancer (click to expand)
To test the connection to the external Endpoint through the load balancer:
-
From a server that has connection to your cluster, such as the server from which you run
kubectl
, usecurl
to connect to the port you specified as the NodePort for your TCP service when you configured the ingress controller. In this example, the NodePort we specified was30681
.nixcurl -H "host: ifconfig.info" 127.0.0.1:30681nixcurl -H "host: ifconfig.info" 127.0.0.1:30681Your IP address should display.
output172.31.35.253
output172.31.35.253
Do you have any suggestions on how we can improve the content of this page?