copyright

lastupdated

keywords

subcollection

years
2014, 2019

2019-09-30

kubernetes, iks, nginx, ingress controller

containers

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:deprecated: .deprecated} {:download: .download} {:preview: .preview}

Setting up Ingress

{: #ingress}

Expose multiple apps in your Kubernetes cluster by creating Ingress resources that are managed by the IBM-provided application load balancer in {{site.data.keyword.containerlong}}. {:shortdesc}

Sample YAMLs

{: #sample_ingress}

Use these sample YAML files to quickly get started with specifying your Ingress resource. {: shortdesc}

Ingress resource to publicly expose an app

Have you already completed the following?

Deploy app
Create app service
Select domain name and TLS secret

You can use the following deployment YAML to create an Ingress resource:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingressresource
spec:
  tls:
  - hosts:
    - <domain>
    secretName: <tls_secret_name>
  rules:
  - host: <domain>
    http:
      paths:
      - path: /<app1_path>
        backend:
          serviceName: <app1_service>
          servicePort: 80
      - path: /<app2_path>
        backend:
          serviceName: <app2_service>
          servicePort: 80

{: codeblock}

Ingress resource to privately expose an app

Have you already completed the following?

Enable private ALB
Deploy app
Create app service
Register custom domain name and TLS secret

You can use the following deployment YAML to create an Ingress resource:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingressresource
  annotations:
    ingress.bluemix.net/ALB-ID: "<private_ALB_ID_1>;<private_ALB_ID_2>"
spec:
  tls:
  - hosts:
    - <domain>
    secretName: <tls_secret_name>
  rules:
  - host: <domain>
    http:
      paths:
      - path: /<app1_path>
        backend:
          serviceName: <app1_service>
          servicePort: 80
      - path: /<app2_path>
        backend:
          serviceName: <app2_service>
          servicePort: 80

{: codeblock}

Prerequisites

{: #config_prereqs}

Before you get started with Ingress, review the following prerequisites. {:shortdesc}

Setting up Ingress requires the following {{site.data.keyword.cloud_notm}} IAM roles:
- Administrator platform role for the cluster
- Manager service role in all namespaces
Ingress is available for standard clusters only and requires at least two worker nodes per zone to ensure high availability and that periodic updates are applied. If you have only one worker in a zone, the ALB cannot receive automatic updates. When automatic updates are rolled out to ALB pods, the pod is reloaded. However, ALB pods have anti-affinity rules to ensure that only one pod is scheduled to each worker node for high availability. Because there is only one ALB pod on one worker, the pod is not restarted so that traffic is not interrupted. The ALB pod is updated to the latest version only when you delete the old pod manually so that the new, updated pod can be scheduled.
If a zone fails, you might see intermittent failures in requests to the Ingress ALB in that zone.
If you restrict network traffic to edge worker nodes, ensure that at least two edge worker nodes are enabled in each zone so that ALBs deploy uniformly.

Classic clusters: Enable a Virtual Router Function (VRF) for your IBM Cloud infrastructure account. To enable VRF, contact your IBM Cloud infrastructure account representative. To check whether a VRF is already enabled, use the ibmcloud account show command. If you cannot or do not want to enable VRF, enable VLAN spanning. When a VRF or VLAN spanning is enabled, the NLB 2.0 can route packets to various subnets in the account.

Planning networking for single or multiple namespaces

{: #multiple_namespaces}

One Ingress resource is required per namespace where you have apps that you want to expose. {:shortdesc}

All apps are in one namespace

{: #one-ns}

If the apps in your cluster are all in the same namespace, one Ingress resource is required to define routing rules for the apps that are exposed there. For example, if you have app1 and app2 exposed by services in a development namespace, you can create an Ingress resource in the namespace. The resource specifies domain.net as the host and registers the paths that each app listens on with domain.net. {: shortdesc}

Apps are in multiple namespaces

{: #multi-ns}

If the apps in your cluster are in different namespaces, you must create one resource per namespace to define rules for the apps that are exposed there. {: shortdesc}

However, you can define a hostname in only one resource. You cannot define the same hostname in multiple resources. To register multiple Ingress resources with the same hostname, you must use a wildcard domain. When a wildcard domain such as *.domain.net is registered, multiple subdomains can all resolve to the same host. Then, you can create an Ingress resource in each namespace and specify a different subdomain in each Ingress resource.

For example, consider the following scenario:

You have two versions of the same app, app1 and app3, for testing purposes.
You deploy the apps in two different namespaces within the same cluster: app1 into the development namespace, and app3 into the staging namespace.

To use the same cluster ALB to manage traffic to these apps, you create the following services and resources:

A Kubernetes service in the development namespace to expose app1.
An Ingress resource in the development namespace that specifies the host as dev.domain.net.
A Kubernetes service in the staging namespace to expose app3.
An Ingress resource in the staging namespace that specifies the host as stage.domain.net.

Now, both URLs resolve to the same domain and are thus both serviced by the same ALB. However, because the resource in the staging namespace is registered with the stage subdomain, the Ingress ALB correctly routes requests from the stage.domain.net/app3 URL to only app3.

{: #wildcard_tls} The IBM-provided Ingress subdomain wildcard, *.<cluster_name>.<region>.containers.appdomain.cloud, is registered by default for your cluster. The IBM-provided TLS certificate is a wildcard certificate and can be used for the wildcard subdomain. If you want to use a custom domain, you must register the custom domain as a wildcard domain such as *.custom_domain.net. To use TLS, you must get a wildcard certificate. {: note}

Multiple domains within a namespace

{: #multi-domains}

Within an individual namespace, you can use one domain to access all the apps in the namespace. If you want to use different domains for the apps within an individual namespace, use a wildcard domain. When a wildcard domain such as *.mycluster.us-south.containers.appdomain.cloud is registered, multiple subdomains all resolve to the same host. Then, you can use one resource to specify multiple subdomain hosts within that resource. Alternatively, you can create multiple Ingress resources in the namespace and specify a different subdomain in each Ingress resource. {: shortdesc}

The IBM-provided Ingress subdomain wildcard, *.<cluster_name>.<region>.containers.appdomain.cloud, is registered by default for your cluster. The IBM-provided TLS certificate is a wildcard certificate and can be used for the wildcard subdomain. If you want to use a custom domain, you must register the custom domain as a wildcard domain such as *.custom_domain.net. To use TLS, you must get a wildcard certificate. {: note}

Exposing apps that are inside your cluster to the public

{: #ingress_expose_public}

Expose apps that are inside your cluster to the public by using the public Ingress ALB. {:shortdesc}

Before you begin:

Review the Ingress prerequisites.
Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

Step 1: Deploy apps and create app services

{: #public_inside_1}

Start by deploying your apps and creating Kubernetes services to expose them. {: shortdesc}

Deploy your app to the cluster. Ensure that you add a label to your deployment in the metadata section of your configuration file, such as app: code. This label is needed to identify all pods where your app runs so that the pods can be included in the Ingress load balancing.

Create a Kubernetes service for each app that you want to expose. Your app must be exposed by a Kubernetes service to be included by the cluster ALB in the Ingress load balancing.

Open your preferred editor and create a service configuration file that is named, for example, myappservice.yaml.

Define a service for the app that the ALB will expose.

apiVersion: v1
kind: Service
metadata:
  name: myappservice
spec:
  selector:
    <selector_key>: <selector_value>
  ports:
   - protocol: TCP
     port: 8080

{: codeblock}

Understanding the ALB service YAML file components
`selector`	Enter the label key (<selector_key>) and value (<selector_value>) pair that you want to use to target the pods where your app runs. To target your pods and include them in the service load balancing, ensure that the <selector_key> and <selector_value> are the same as the key/value pair in the `spec.template.metadata.labels` section of your deployment YAML.
`port`	The port that the service listens on.

Save your changes.
Create the service in your cluster. If apps are deployed in multiple namespaces in your cluster, ensure that the service deploys into the same namespace as the app that you want to expose.
```
kubectl apply -f myappservice.yaml [-n <namespace>]
```
{: pre}
Repeat these steps for every app that you want to expose.

Step 2: Select an app domain

{: #public_inside_2}

When you configure the public ALB, you choose the domain that your apps will be accessible through. {: shortdesc}

You can use the IBM-provided domain, such as mycluster-12345.us-south.containers.appdomain.cloud/myapp, to access your app from the internet. To use a custom domain instead, you can set up a CNAME record to map your custom domain to the IBM-provided domain or set up an A record with your DNS provider that uses the ALB's public IP address.

To use the IBM-provided Ingress domain:

Get the IBM-provided domain. Replace <cluster_name_or_ID> with the name of the cluster where the app is deployed.

ibmcloud ks cluster get --cluster <cluster_name_or_ID> | grep Ingress

{: pre}

Example output:

Ingress Subdomain:      mycluster-12345.us-south.containers.appdomain.cloud
Ingress Secret:         <tls_secret>

{: screen}

To use a custom domain:

Create a custom domain. To register your custom domain, work with your Domain Name Service (DNS) provider or {{site.data.keyword.cloud_notm}} DNS. If the apps that you want Ingress to expose are in different namespaces in one cluster, register the custom domain as a wildcard domain, such as *.custom_domain.net. Note that domains are limited to 255 characters or fewer.
Define an alias for your custom domain by specifying the IBM-provided domain as a Canonical Name record (CNAME). To find the IBM-provided Ingress domain, run ibmcloud ks cluster get --cluster <cluster_name> and look for the Ingress subdomain field.

Step 3: Select TLS termination

{: #public_inside_3}

After you choose the app domain, you choose whether to use TLS termination. {: shortdesc}

The ALB load balances HTTP network traffic to the apps in your cluster. To also load balance incoming HTTPS connections, you can configure the ALB to decrypt the network traffic and forward the decrypted request to the apps that are exposed in your cluster.

If you use the IBM-provided Ingress subdomain, you can use the IBM-provided TLS certificate. IBM-provided TLS certificates are signed by LetsEncrypt and are fully managed by IBM. The certificates expire every 90 days and are automatically renewed 37 days before they expire. For more information about wildcard TLS certification, see this note.
If you use a custom domain, you can use your own TLS certificate to manage TLS termination. The ALB first checks for a secret in the namespace that the app is in, then in default, and finally in ibm-cert-store. If you have apps in one namespace only, you can import or create a TLS secret for the certificate in that same namespace. If you have apps in multiple namespaces, import or create a TLS secret for the certificate in the default namespace so that the ALB can access and use the certificate in every namespace. In the Ingress resources that you define for each namespace, specify the name of the secret that is in the default namespace. For more information about wildcard TLS certification, see this note. Note: TLS certificates that contain pre-shared keys (TLS-PSK) are not supported.

If you use the IBM-provided Ingress domain:

Get the IBM-provided TLS secret for your cluster.

ibmcloud ks cluster get --cluster <cluster_name_or_ID> | grep Ingress

{: pre}

Example output:

Ingress Subdomain:      mycluster-12345.us-south.containers.appdomain.cloud
Ingress Secret:         <tls_secret>

{: screen}

If you use a custom domain:

If a TLS certificate is stored in {{site.data.keyword.cloudcerts_long_notm}} that you want to use, you can import its associated secret into your cluster by running the following command:

ibmcloud ks alb cert deploy --secret-name <secret_name> --cluster <cluster_name_or_ID> --cert-crn <certificate_crn>

{: pre}

Make sure that you do not create the secret with the same name as the IBM-provided Ingress secret. You can get the name of the IBM-provided Ingress secret by running ibmcloud ks cluster get --cluster <cluster_name_or_ID> | grep Ingress. {: note}

When you import a certificate with this command, the certificate secret is created in a namespace called ibm-cert-store. A reference to this secret is then created in the default namespace, which any Ingress resource in any namespace can access. When the ALB is processing requests, it follows this reference to pick up and use the certificate secret from the ibm-cert-store namespace.

If you do not have a TLS certificate ready, follow these steps:

Generate a certificate authority (CA) cert and key from your certificate provider. If you have your own domain, purchase an official TLS certificate for your domain. Make sure the CN is different for each certificate.
Convert the cert and key into base-64.
1. Encode the cert and key into base-64 and save the base-64 encoded value in a new file.
```
openssl base64 -in tls.key -out tls.key.base64
```
  {: pre}
2. View the base-64 encoded value for your cert and key.
```
cat tls.key.base64
```
  {: pre}

Create a secret YAML file using the cert and key.

apiVersion: v1
kind: Secret
metadata:
  name: ssl-my-test
type: Opaque
data:
  tls.crt: <client_certificate>
  tls.key: <client_key>

{: codeblock}

Create the certificate as a Kubernetes secret.
```
kubectl apply -f ssl-my-test
```
{: pre} Make sure that you do not create the secret with the same name as the IBM-provided Ingress secret. You can get the name of the IBM-provided Ingress secret by running ibmcloud ks cluster get --cluster <cluster_name_or_ID> | grep Ingress. {: note}

Step 4: Create the Ingress resource

{: #public_inside_4}

Ingress resources define the routing rules that the ALB uses to route traffic to your app service. {: shortdesc}

If your cluster has multiple namespaces where apps are exposed, one Ingress resource is required per namespace. However, each namespace must use a different host. You must register a wildcard domain and specify a different subdomain in each resource. For more information, see Planning networking for single or multiple namespaces. {: note}

Open your preferred editor and create an Ingress configuration file that is named, for example, myingressresource.yaml.

Define an Ingress resource in your configuration file that uses the IBM-provided domain or your custom domain to route incoming network traffic to the services that you created earlier.

Example YAML that does not use TLS:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingressresource
spec:
  rules:
  - host: <domain>
    http:
      paths:
      - path: /<app1_path>
        backend:
          serviceName: <app1_service>
          servicePort: 80
      - path: /<app2_path>
        backend:
          serviceName: <app2_service>
          servicePort: 80

{: codeblock}

Example YAML that uses TLS:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingressresource
spec:
  tls:
  - hosts:
    - <domain>
    secretName: <tls_secret_name>
  rules:
  - host: <domain>
    http:
      paths:
      - path: /<app1_path>
        backend:
          serviceName: <app1_service>
          servicePort: 80
      - path: /<app2_path>
        backend:
          serviceName: <app2_service>
          servicePort: 80

{: codeblock}

Understanding the YAML file components
`tls.hosts`	To use TLS, replace <domain> with the IBM-provided Ingress subdomain or your custom domain. Note: If your apps are exposed by services in different namespaces in one cluster, append a wildcard subdomain to the beginning of the domain, such as `subdomain1.custom_domain.net` or `subdomain1.mycluster.us-south.containers.appdomain.cloud`. Use a unique subdomain for each resource that you create in the cluster. Do not use * for your host or leave the host property empty to avoid failures during Ingress creation.
`tls.secretName`	If you use the IBM-provided Ingress domain, replace <tls_secret_name> with the name of the IBM-provided Ingress secret. If you use a custom domain, replace <tls_secret_name> with the secret that you created earlier that holds your custom TLS certificate and key. If you imported a certificate from {{site.data.keyword.cloudcerts_short}}, you can run `ibmcloud ks alb cert get --cluster --cert-crn` to see the secrets that are associated with a TLS certificate.
`host`	Replace <domain> with the IBM-provided Ingress subdomain or your custom domain. Note: If your apps are exposed by services in different namespaces in one cluster, append a wildcard subdomain to the beginning of the domain, such as `subdomain1.custom_domain.net` or `subdomain1.mycluster.us-south.containers.appdomain.cloud`. Use a unique subdomain for each resource that you create in the cluster. Do not use * for your host or leave the host property empty to avoid failures during Ingress creation.
`path`	Replace <app_path> with a slash or the path that your app is listening on. The path is appended to the IBM-provided or your custom domain to create a unique route to your app. When you enter this route into a web browser, network traffic is routed to the ALB. The ALB looks up the associated service and sends network traffic to the service. The service then forwards the traffic to the pods where the app runs. Many apps do not listen on a specific path, but use the root path and a specific port. In this case, define the root path as `/` and do not specify an individual path for your app. Examples: For `http://domain/`, enter `/` as the path. For `http://domain/app1_path`, enter `/app1_path` as the path. To configure Ingress to listen on a path that is different than the path that your app listens on, you can use the [rewrite annotation](/docs/containers?topic=containers-ingress_annotation#rewrite-path).
`serviceName`	Replace <app1_service> and <app2_service>, and so on, with the name of the services you created to expose your apps. If your apps are exposed by services in different namespaces in the cluster, include only app services that are in the same namespace. You must create one Ingress resource for each namespace where you have apps that you want to expose.
`servicePort`	The port that your service listens to. Use the same port that you defined when you created the Kubernetes service for your app.

Create the Ingress resource for your cluster. Ensure that the resource deploys into the same namespace as the app services that you specified in the resource.
```
kubectl apply -f myingressresource.yaml -n <namespace>
```
{: pre}
Verify that the Ingress resource was created successfully.
```
kubectl describe ingress myingressresource
```
{: pre}
1. If messages in the events describe an error in your resource configuration, change the values in your resource file and reapply the file for the resource.

Your Ingress resource is created in the same namespace as your app services. Your apps in this namespace are registered with the cluster's Ingress ALB.

Step 5: Access your app from the internet

{: #public_inside_5}

In a web browser, enter the URL of the app service to access. {: shortdesc}

https://<domain>/<app1_path>

{: codeblock}

If you exposed multiple apps, access those apps by changing the path that is appended to the URL.

https://<domain>/<app2_path>

{: codeblock}

If you use a wildcard domain to expose apps in different namespaces, access those apps with their own subdomains.

http://<subdomain1>.<domain>/<app1_path>

{: codeblock}

http://<subdomain2>.<domain>/<app1_path>

{: codeblock}

Having trouble connecting to your app through Ingress? Try debugging Ingress. {: tip}

Exposing apps that are outside your cluster to the public

{: #external_endpoint}

Expose apps that are outside your cluster to the public by including them in public Ingress ALB load balancing. Incoming public requests on the IBM-provided or your custom domain are forwarded automatically to the external app. {: shortdesc}

Before you begin:

Review the Ingress prerequisites.
Ensure that the external app that you want to include into the cluster load balancing can be accessed by using a public IP address.
VPC clusters: In order to forward requests to the public external endpoint of your app, your VPC subnets must have a public gateway attached.
Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

To expose apps that are outside your cluster to the public:

Create a Kubernetes service for your cluster that will forward incoming requests to an external endpoint that you will create.

Open your preferred editor and create a service configuration file that is named, for example, myexternalservice.yaml.

Define a service for the app that the ALB will expose.

apiVersion: v1
kind: Service
metadata:
  name: myexternalservice
spec:
  ports:
   - protocol: TCP
     port: 8080

{: codeblock}

Understanding the ALB service file components

Understanding the YAML file components
`metadata.name`	Replace `<myexternalservice>` with a name for your service. Learn more about [securing your personal information](/docs/containers?topic=containers-security#pi) when you work with Kubernetes resources.
`port`	The port that the service listens on.

Save your changes.
Create the Kubernetes service for your cluster.
```
kubectl apply -f myexternalservice.yaml
```
{: pre}

Configure a Kubernetes endpoint that defines the external location of the app that you want to include into the cluster load balancing.

Open your preferred editor and create an endpoint configuration file that is named, for example, myexternalendpoint.yaml.

Define your external endpoint. Include all public IP addresses and ports that you can use to access your external app.

kind: Endpoints
apiVersion: v1
metadata:
  name: myexternalservice
subsets:
  - addresses:
      - ip: <external_IP1>
      - ip: <external_IP2>
    ports:
      - port: <external_port>

{: codeblock}

Understanding the YAML file components
`name`	Replace `<myexternalendpoint>` with the name of the Kubernetes service that you created earlier.
`ip`	Replace <external_IP> with the public IP addresses to connect to your external app.
`port`	Replace <external_port> with the port that your external app listens to.

Save your changes.
Create the Kubernetes endpoint for your cluster.
```
kubectl apply -f myexternalendpoint.yaml
```
{: pre}

Continue with the steps in "Exposing apps that are inside your cluster to the public", Step 2: Select an app domain.

Classic clusters: Exposing apps to a private network

{: #ingress_expose_private}

Expose apps to a private network by using the private Ingress ALBs in a classic cluster. {:shortdesc}

To use a private ALB, you must first enable the private ALB. Because private VLAN-only classic clusters are not assigned an IBM-provided Ingress subdomain, no Ingress secret is created during cluster setup. To expose your apps to the private network, you must register your ALB with a custom domain and, optionally, import your own TLS certificate.

Before you begin:

Review the Ingress prerequisites.
If you have a classic cluster with worker nodes that are connected to a private VLAN only you must configure a DNS service that is available on the private network .

Step 1: Deploy apps and create app services

{: #private_1}

Start by deploying your apps and creating Kubernetes services to expose them. {: shortdesc}

Deploy your app to the cluster. Ensure that you add a label to your deployment in the metadata section of your configuration file, such as app: code. This label is needed to identify all pods where your app runs so that the pods can be included in the Ingress load balancing.

Create a Kubernetes service for each app that you want to expose. Your app must be exposed by a Kubernetes service to be included by the cluster ALB in the Ingress load balancing.

Open your preferred editor and create a service configuration file that is named, for example, myappservice.yaml.

Define a service for the app that the ALB will expose.

apiVersion: v1
kind: Service
metadata:
  name: myappservice
spec:
  selector:
    <selector_key>: <selector_value>
  ports:
   - protocol: TCP
     port: 8080

{: codeblock}

Understanding the ALB service YAML file components
`selector`	Enter the label key (<selector_key>) and value (<selector_value>) pair that you want to use to target the pods where your app runs. To target your pods and include them in the service load balancing, ensure that the <selector_key> and <selector_value> are the same as the key/value pair in the `spec.template.metadata.labels` section of your deployment YAML.
`port`	The port that the service listens on.

Save your changes.
Create the service in your cluster. If apps are deployed in multiple namespaces in your cluster, ensure that the service deploys into the same namespace as the app that you want to expose.
```
kubectl apply -f myappservice.yaml [-n <namespace>]
```
{: pre}
Repeat these steps for every app that you want to expose.

Step 2: Enable the default private ALB

{: #private_ingress}

When you create a standard cluster, a private ALB is created in each zone that you have worker nodes and assigned a private IP address. However, the default private ALB in each zone is not automatically enabled. You must first enable each private ALB. {:shortdesc}

Get the private ALB IDs for your cluster.

ibmcloud ks alb ls --cluster <cluster_name>

{: pre}

The field Status for private ALBs is disabled.

ALB ID                                            Enabled   Status     Type      ALB IP          Zone    Build                          ALB VLAN ID   NLB Version
private-crdf253b6025d64944ab99ed63bb4567b6-alb1   false     disabled   private   -               dal10   ingress:411/ingress-auth:315   2234947       -
public-crdf253b6025d64944ab99ed63bb4567b6-alb1    true      enabled    public    169.xx.xxx.xxx  dal10   ingress:411/ingress-auth:315   2234945       -

{: screen}

Enable the private ALBs. Run this command for the ID of each private ALB that you want to enable. If you want to specify an IP address for the ALB, include the IP address in the --user-ip flag.

ibmcloud ks alb configure vpc-classic --alb-id <private_ALB_ID> --enable

{: pre}

Step 3: Map your custom domain

{: #private_3}

When you configure the private ALBs, you must expose your apps by using a custom domain. {: shortdesc}

Private VLAN-only classic clusters:

Configure your own DNS service that is available on your private network .
Create a custom domain through your DNS provider. If the apps that you want Ingress to expose are in different namespaces in one cluster, register the custom domain as a wildcard domain, such as *.custom_domain.net.
Using your private DNS service, map your custom domain to the portable private IP addresses of the ALBs by adding the IP addresses as A records. To find the portable private IP addresses of the ALBs, run ibmcloud ks alb get --alb-id <private_alb_ID> for each ALB.

Private and public VLAN classic clusters:

Create a custom domain. To register your custom domain, work with your Domain Name Service (DNS) provider or {{site.data.keyword.cloud_notm}} DNS. If the apps that you want Ingress to expose are in different namespaces in one cluster, register the custom domain as a wildcard domain, such as *.custom_domain.net. Note that domains are limited to 255 characters or fewer.
Map your custom domain to the portable private IP addresses of the ALBs by adding the IP addresses as A records. To find the portable private IP addresses of the ALBs, run ibmcloud ks alb get --alb-id <private_alb_ID> for each ALB.

Step 4: Select TLS termination

{: #private_4}

After you map your custom domain, choose whether to use TLS termination. {: shortdesc}

The ALB load balances HTTP network traffic to the apps in your cluster. To also load balance incoming HTTPS connections, you can configure the ALB to decrypt the network traffic and forward the decrypted request to the apps that are exposed in your cluster.

Because private VLAN-only clusters are not assigned an IBM-provided Ingress domain, no Ingress secret is created during the cluster setup. You can use your own TLS certificate to manage TLS termination. The ALB first checks for a secret in the namespace that the app is in, then in default, and finally in ibm-cert-store. If you have apps in one namespace only, you can import or create a TLS secret for the certificate in that same namespace. If you have apps in multiple namespaces, import or create a TLS secret for the certificate in the default namespace so that the ALB can access and use the certificate in every namespace. In the Ingress resources that you define for each namespace, specify the name of the secret that is in the default namespace. For more information about wildcard TLS certification, see this note. Note: TLS certificates that contain pre-shared keys (TLS-PSK) are not supported.

If a TLS certificate is stored in {{site.data.keyword.cloudcerts_long_notm}} that you want to use, you can import its associated secret into your cluster by running the following command:

ibmcloud ks alb cert deploy --secret-name <secret_name> --cluster <cluster_name_or_ID> --cert-crn <certificate_crn>

{: pre}

When you import a certificate with this command, the certificate secret is created in a namespace called ibm-cert-store. A reference to this secret is then created in the default namespace, which any Ingress resource in any namespace can access. When the ALB is processing requests, it follows this reference to pick up and use the certificate secret from the ibm-cert-store namespace.

Step 5: Create the Ingress resource

{: #private_5}

Ingress resources define the routing rules that the ALB uses to route traffic to your app service. {: shortdesc}

If your cluster has multiple namespaces where apps are exposed, one Ingress resource is required per namespace. However, each namespace must use a different host. You must register a wildcard domain and specify a different subdomain in each resource. For more information, see Planning networking for single or multiple namespaces. {: note}

Open your preferred editor and create an Ingress configuration file that is named, for example, myingressresource.yaml.

Define an Ingress resource in your configuration file that uses your custom domain to route incoming network traffic to the services that you created earlier.

Example YAML that does not use TLS:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingressresource
  annotations:
    ingress.bluemix.net/ALB-ID: "<private_ALB_ID_1>;<private_ALB_ID_2>"
spec:
  rules:
  - host: <domain>
    http:
      paths:
      - path: /<app1_path>
        backend:
          serviceName: <app1_service>
          servicePort: 80
      - path: /<app2_path>
        backend:
          serviceName: <app2_service>
          servicePort: 80

{: codeblock}

Example YAML that uses TLS:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingressresource
  annotations:
    ingress.bluemix.net/ALB-ID: "<private_ALB_ID_1>;<private_ALB_ID_2>"
spec:
  tls:
  - hosts:
    - <domain>
    secretName: <tls_secret_name>
  rules:
  - host: <domain>
    http:
      paths:
      - path: /<app1_path>
        backend:
          serviceName: <app1_service>
          servicePort: 80
      - path: /<app2_path>
        backend:
          serviceName: <app2_service>
          servicePort: 80

{: codeblock}

Understanding the YAML file components
`ingress.bluemix.net/ALB-ID`	Replace <private_ALB_ID> with the ID for your private ALB. If you have a multizone cluster and enabled multiple private ALBs, include the ID of each ALB. Run `ibmcloud ks alb ls --cluster` to find the ALB IDs. For more information about this Ingress annotation, see [Private application load balancer routing](/docs/containers?topic=containers-ingress_annotation#alb-id).
`tls.hosts`	To use TLS, replace <domain> with your custom domain. Note: If your apps are exposed by services in different namespaces in one cluster, append a wildcard subdomain to the beginning of the domain, such as `subdomain1.custom_domain.net`. Use a unique subdomain for each resource that you create in the cluster. Do not use * for your host or leave the host property empty to avoid failures during Ingress creation.
`tls.secretName`	Replace <tls_secret_name> with the name of the secret that you created earlier and that holds your custom TLS certificate and key. If you imported a certificate from {{site.data.keyword.cloudcerts_short}}, you can run `ibmcloud ks alb cert get --cluster --cert-crn` to see the secrets that are associated with a TLS certificate.
`host`	Replace <domain> with your custom domain. Note: If your apps are exposed by services in different namespaces in one cluster, append a wildcard subdomain to the beginning of the domain, such as `subdomain1.custom_domain.net`. Use a unique subdomain for each resource that you create in the cluster. Do not use * for your host or leave the host property empty to avoid failures during Ingress creation.
`path`	Replace <app_path> with a slash or the path that your app is listening on. The path is appended to your custom domain to create a unique route to your app. When you enter this route into a web browser, network traffic is routed to the ALB. The ALB looks up the associated service and sends network traffic to the service. The service then forwards the traffic to the pods where the app runs. Many apps do not listen on a specific path, but use the root path and a specific port. In this case, define the root path as `/` and do not specify an individual path for your app. Examples: For `http://domain/`, enter `/` as the path. For `http://domain/app1_path`, enter `/app1_path` as the path. To configure Ingress to listen on a path that is different than the path that your app listens on, you can use the [rewrite annotation](/docs/containers?topic=containers-ingress_annotation#rewrite-path).
`serviceName`	Replace <app1_service> and <app2_service>, and so on, with the name of the services you created to expose your apps. If your apps are exposed by services in different namespaces in the cluster, include only app services that are in the same namespace. You must create one Ingress resource for each namespace where you have apps that you want to expose.
`servicePort`	The port that your service listens to. Use the same port that you defined when you created the Kubernetes service for your app.

Create the Ingress resource for your cluster. Ensure that the resource deploys into the same namespace as the app services that you specified in the resource.
```
kubectl apply -f myingressresource.yaml -n <namespace>
```
{: pre}
Verify that the Ingress resource was created successfully.
```
kubectl describe ingress myingressresource
```
{: pre}
1. If messages in the events describe an error in your resource configuration, change the values in your resource file and reapply the file for the resource.

Your Ingress resource is created in the same namespace as your app services. Your apps in this namespace are registered with the cluster's Ingress ALB.

Step 6: Access your app from your private network

{: #private_6}

Before you can access your app, make sure that you can access a DNS service.

Public and private VLAN: To use the default external DNS provider, you must configure edge nodes with public access and configure a Virtual Router Appliance .
Private VLAN only: You must configure a DNS service that is available on the private network .

From within your private network firewall, enter the URL of the app service in a web browser.

https://<domain>/<app1_path>

{: codeblock}

If you exposed multiple apps, access those apps by changing the path that is appended to the URL.

https://<domain>/<app2_path>

{: codeblock}

If you use a wildcard domain to expose apps in different namespaces, access those apps with their own subdomains.

http://<subdomain1>.<domain>/<app1_path>

{: codeblock}

http://<subdomain2>.<domain>/<app1_path>

{: codeblock}

For a comprehensive tutorial on how to secure microservice-to-microservice communication across your clusters by using the private ALB with TLS, check out this blog post External link icon . {: tip}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cs_ingress.md

cs_ingress.md

Setting up Ingress

Sample YAMLs

Prerequisites

Planning networking for single or multiple namespaces

All apps are in one namespace

Apps are in multiple namespaces

Multiple domains within a namespace

Exposing apps that are inside your cluster to the public

Step 1: Deploy apps and create app services

Step 2: Select an app domain

Step 3: Select TLS termination

Step 4: Create the Ingress resource

Step 5: Access your app from the internet

Exposing apps that are outside your cluster to the public

Classic clusters: Exposing apps to a private network

Step 1: Deploy apps and create app services

Step 2: Enable the default private ALB

Step 3: Map your custom domain

Step 4: Select TLS termination

Step 5: Create the Ingress resource

Step 6: Access your app from your private network

Files

cs_ingress.md

Latest commit

History

cs_ingress.md

File metadata and controls

Setting up Ingress

Sample YAMLs

Prerequisites

Planning networking for single or multiple namespaces

All apps are in one namespace

Apps are in multiple namespaces

Multiple domains within a namespace

Exposing apps that are inside your cluster to the public

Step 1: Deploy apps and create app services

Step 2: Select an app domain

Step 3: Select TLS termination

Step 4: Create the Ingress resource

Step 5: Access your app from the internet

Exposing apps that are outside your cluster to the public

Classic clusters: Exposing apps to a private network

Step 1: Deploy apps and create app services

Step 2: Enable the default private ALB

Step 3: Map your custom domain

Step 4: Select TLS termination

Step 5: Create the Ingress resource

Step 6: Access your app from your private network