Registering a DNS subdomain for an NLB
Classic infrastructure
This content is specific to NLBs in classic clusters. For VPC clusters, see Registering a VPC load balancer hostname with a DNS subdomain.
After you set up network load balancers (NLBs), you can create DNS entries for the NLB IPs by creating subdomains. You can also set up TCP/HTTP(S) monitors to health check the NLB IP addresses behind each subdomain.
- Subdomain
- When you create a public NLB in a single-zone or multizone cluster, you can expose your app to the internet by creating a subdomain for the NLB IP address. Additionally, IBM Cloud takes care of generating and maintaining the wildcard SSL certificate
for the subdomain for you. In multizone clusters, you can create a subdomain and add the NLB IP address in each zone to that subdomain DNS entry. For example, if you deployed NLBs for your app in three zones in US-South, you can create the
subdomain
mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud
for the three NLB IP addresses. When a user accesses your app subdomain, the client accesses one of these IPs at random, and the request is sent to that NLB.
You currently can't create subdomains for private NLBs.
- Health check monitor
- Enable health checks on the NLB IP addresses behind a single subdomain to determine whether they are available or not. When you enable a monitor for your subdomain, the monitor health checks each NLB IP and keeps the DNS lookup results updated
based on these health checks. For example, if your NLBs have IP addresses
1.1.1.1
,2.2.2.2
, and3.3.3.3
, a normal operation DNS lookup of your subdomain returns all 3 IPs, 1 of which the client accesses at random. If the NLB with IP address3.3.3.3
becomes unavailable for any reason, such as due to zone failure, then the health check for that IP fails, the monitor removes the failed IP from the subdomain, and the DNS lookup returns only the healthy1.1.1.1
and2.2.2.2
IPs.
You can see all subdomains that are registered for NLB IPs in your cluster by running the following command.
ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>
DNS microservice updates are asynchronous and might take several minutes to apply. Note that if you run an ibmcloud ks nlb-dns
command and receive a 200 confirmation message, you might still have to wait for your changes to be implemented.
To check the status of your subdomain, run ibmcloud ks nlb-dns ls
and find the Status
column in the output.
Registering NLB IPs with a DNS subdomain
Expose your app to the public internet by creating a subdomain for the network load balancer (NLB) IP address.
Before you begin:
- Review the following limitations.
- You can't create subdomains for private NLBs.
- You can register up to 128 subdomains. This limit can be lifted on request by opening a support case.
- Create an NLB for your app in a single-zone cluster or create NLBs in each zone of a multizone cluster.
To create a subdomain for one or more NLB IP addresses:
-
Get the EXTERNAL-IP address for your NLB. If you have NLBs in each zone of a multizone cluster that expose one app, get the IPs for each NLB.
kubectl get svc
In the following example output, the NLB EXTERNAL-IPs are
168.2.4.5
and88.2.4.5
.NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE lb-myapp-dal10 LoadBalancer 172.21.xxx.xxx 168.2.4.5 1883:30303/TCP 6d lb-myapp-dal12 LoadBalancer 172.21.xxx.xxx 88.2.4.5 1883:31303/TCP 6d
-
Register the IP by creating a DNS subdomain. To specify multiple IP addresses, use multiple
--ip
options.ibmcloud ks nlb-dns create classic --cluster <cluster_name_or_id> --ip <NLB_IP> --ip <NLB2_IP>
-
Verify that the subdomain is created.
ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>
Example output
Hostname IP(s) Health Monitor SSL Cert Status SSL Cert Secret Name mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud ["168.2.4.5"] None created <certificate>
-
Optional: Set up a custom domain to point to the IBM-provided subdomain that you created in the previous step.
- Register a custom domain by working with your Domain Name Service (DNS) provider.
- Register a custom domain using IBM Cloud DNS.
You can also register a custom domain by using the
service.kubernetes.io/ibm-load-balancer-cloud-provider-dns-name
annotation in your Load Balancer configuration. -
Define an alias for your custom domain by specifying the IBM-provided subdomain as a Canonical Name record (CNAME).
-
In a web browser, enter the URL to access your app through the subdomain that you created.
Next, you can enable health checks on the subdomain by creating a health monitor.
Understanding the subdomain format
Subdomains for NLBs follow the format <cluster_name>-<globally_unique_account_HASH>-0001.<region>.containers.appdomain.cloud
.
For example, a subdomain that you create for an NLB might look like mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud
. The following table describes each component of the subdomain.
NLB subdomain component | Description |
---|---|
* |
The wildcard for the subdomain is registered by default for your cluster. |
<cluster_name> |
The name of your cluster. - If the cluster name is 26 characters or fewer and the cluster name is unique in this region, the entire cluster name is included and is not modified:
|
<globally_unique_account_HASH> |
A globally unique HASH is created for your IBM Cloud account. All subdomains that you create for NLBs in clusters in your account use this globally unique HASH. |
0001 |
Acts as a counter for each subdomain that you create. |
<region> |
The region that the cluster is created in. |
containers.appdomain.cloud |
The subdomain for IBM Cloud Kubernetes Service subdomains. |
Enable health checks on a subdomain by creating a health monitor
Enable health checks on the NLB IP addresses behind a single subdomain to determine whether they are available or not.
Before you begin, register NLB IPs with a DNS subdomain.
-
Get the name of your subdomain. In the output, note that the host has a monitor Status of
Unconfigured
.ibmcloud ks nlb-dns monitor ls --cluster <cluster_name_or_id>
Example output
Hostname Status Type Port Path mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud Unconfigured N/A 0 N/A
-
Create a health check monitor for the subdomain. If you don't include a configuration parameter, the default value is used.
ibmcloud ks nlb-dns monitor configure --cluster <cluster_name_or_id> --nlb-host <host_name> --enable --description <description> --type <type> --method <method> --path <path> --timeout <timeout> --retries <retries> --interval <interval> --port <port> --header <header> --expected-body <expected-body> --expected-codes <expected-codes> --follows-redirects <true> --allows-insecure <true>
-c, --cluster <cluster_name_or_ID>
- Required: The name or ID of the cluster where the subdomain is registered.
--nlb-host <host_name>
- Required: The subdomain to enable a health check monitor for.
--enable
- Required: Enable the health check monitor for the subdomain.
--description <description>
- A description of the health monitor.
--type <type>
- The protocol to use for the health check:
HTTP
,HTTPS
, orTCP
. Default:HTTP
. --method <method>
- The method to use for the health check. Default for
type
HTTP
andHTTPS
:GET
. Default fortype
TCP
:connection_established
--path <path>
- When
type
isHTTPS
: The endpoint path to health check against. Default:/
--timeout <timeout>
- The timeout, in seconds, before the IP is considered unhealthy. Default:
5
. --retries <retries>
- When a timeout occurs, the number of retries to attempt before the IP is considered unhealthy. Retries are attempted immediately. Default:
2
. --interval <interval>
- The interval, in seconds, between each health check. Short intervals might improve failover time, but increase load on the IPs. Default:
60
. --port <port>
- The port number to connect to for the health check. When
type
isTCP
, this parameter is required. Whentype
isHTTP
orHTTPS
, define the port only if you use a port other than 80 for HTTP or 443 for HTTPS. Default for TCP:0
. Default for HTTP:80
. Default for HTTPS:443
. --header <header>
- When
type
isHTTP
orHTTPS
: The HTTP request headers to send in the health check, such as a Host header. The User-Agent header can't be overridden. To add more than one header to the requests, specify this option multiple times. This option accepts values in the following format:--header Header-Name=value
. When updating a monitor, the existing headers are replaced by the ones that you specify. To delete all existing headers, specify the option with an empty value (--header ""
). --expected-body <expected-body>
- When
type
isHTTP
orHTTPS
: A case-insensitive substring that the health check looks for in the response body. If this string is not found, the IP is considered unhealthy. --expected-codes <expected-codes>
- When
type
isHTTP
orHTTPS
: HTTP codes that the health check looks for in the response. If the HTTP code is not found, the IP is considered unhealthy. Default:2xx
. --allows-insecure <true>
- When
type
isHTTP
orHTTPS
: Set totrue
to not validate the certificate. --follows-redirects <true>
- When
type
isHTTP
orHTTPS
: Set totrue
to follow any redirects that are returned by the IP.
Example command
ibmcloud ks nlb-dns monitor configure --cluster mycluster --nlb-host mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud --enable --description "Login page monitor" --type HTTPS --method GET --path / --timeout 5 --retries 2 --interval 60 --header Host=example.com --header Origin=https://akamai.com --expected-body "healthy" --expected-codes 2xx --follows-redirects true
-
Verify that the health check monitor is configured with the correct settings.
ibmcloud ks nlb-dns monitor get --cluster <cluster_name_or_id> --nlb-host <host_name>
Example output
Created On: 2019-04-24 09:01:59.781392 +0000 UTC Modified On: 2020-02-26 15:39:05.273217 +0000 UTC Type: https Description: Health check monitor for ingress public hostname Method: GET Path: /alive Expected Body: - Expected Codes: 2xx Follow Redirects: false Allow Insecure: true Port: 443 Timeout: 5 Retries: 2 Interval: 15 Headers: Origin: https://akamai.com Host: example.com Health Monitor Apply Properties Status: success
-
View the health check status of your subdomain.
ibmcloud ks nlb-dns monitor ls --cluster <cluster_name_or_id>
Example output
Hostname Status Type Port Path mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud Healthy https 443 /alive
Updating and removing IPs and monitors from subdomains
You can add and remove NLB IP addresses from subdomains that you have generated. You can also disable and enable health check monitors for subdomains as needed.
NLB IPs
If you later add more NLBs in other zones of your cluster to expose the same app, you can add the NLB IPs to the existing subdomain.
ibmcloud ks nlb-dns add --cluster <cluster_name_or_id> --ip <NLB_IP> --ip <NLB2_IP> ... --nlb-host <host_name>
You can also remove IP addresses of NLBs that you no longer want to be registered with a subdomain. Note that you must run the following command for each IP address that you want to remove. If you remove all IPs from a subdomain, the subdomain still exists but no IPs are associated with it.
ibmcloud ks nlb-dns rm classic --cluster <cluster_name_or_id> --ip <ip> --nlb-host <host_name>
Health check monitors
If you need to change your health monitor configuration, you can change specific settings. Include only the options for the settings that you want to change.
ibmcloud ks nlb-dns monitor configure --cluster <cluster_name_or_id> --nlb-host <host_name> --description <description> --type <type> --method <method> --path <path> --timeout <timeout> --retries <retries> --interval <interval> --port <port> --header <header> --expected-body <expected-body> --expected-codes <expected-codes> --follows-redirects <true> --allows-insecure <true>
You can disable the health check monitor for a subdomain at any time by running the following command:
ibmcloud ks nlb-dns monitor disable --cluster <cluster_name_or_id> --nlb-host <host_name>
To re-enable a monitor for a subdomain, run the following command:
ibmcloud ks nlb-dns monitor enable --cluster <cluster_name_or_id> --nlb-host <host_name>