Configuring ingress cluster traffic using an Ingress Controller

OKD provides methods for communicating from outside the cluster with services running in the cluster. This method uses an Ingress Controller.

Using Ingress Controllers and routes

The Ingress Operator manages Ingress Controllers and wildcard DNS.

Using an Ingress Controller is the most common way to allow external access to an OKD cluster.

An Ingress Controller is configured to accept external requests and proxy them based on the configured routes. This is limited to HTTP, HTTPS using SNI, and TLS using SNI, which is sufficient for web applications and services that work over TLS with SNI.

Work with your administrator to configure an Ingress Controller to accept external requests and proxy them based on the configured routes.

The administrator can create a wildcard DNS entry and then set up an Ingress Controller. Then, you can work with the edge Ingress Controller without having to contact the administrators.

By default, every ingress controller in the cluster can admit any route created in any project in the cluster.

The Ingress Controller:

  • Has two replicas by default, which means it should be running on two worker nodes.

  • Can be scaled up to have more replicas on more nodes.

The procedures in this section require prerequisites performed by the cluster administrator.

Prerequisites

Before starting the following procedures, the administrator must:

  • Set up the external port to the cluster networking environment so that requests can reach the cluster.

  • Make sure there is at least one user with cluster admin role. To add this role to a user, run the following command:

    1. $ oc adm policy add-cluster-role-to-user cluster-admin username

  • Have an OKD cluster with at least one master and at least one node and a system outside the cluster that has network access to the cluster. This procedure assumes that the external system is on the same subnet as the cluster. The additional networking required for external systems on a different subnet is out-of-scope for this topic.

Creating a project and service

If the project and service that you want to expose do not exist, first create the project, then the service.

If the project and service already exist, skip to the procedure on exposing the service to create a route.

Prerequisites

  • Install the oc CLI and log in as a cluster administrator.

Procedure

  1. Create a new project for your service:

    1. $ oc new-project <project_name>

    For example:

    1. $ oc new-project myproject

  2. Use the oc new-app command to create a service. For example:

    1. $ oc new-app \
    2.     -e MYSQL_USER=admin \
    3.     -e MYSQL_PASSWORD=redhat \
    4.     -e MYSQL_DATABASE=mysqldb \
    5.     registry.redhat.io/rhscl/mysql-80-rhel7

  3. Run the following command to see that the new service is created:

    1. $ oc get svc -n myproject

    Example output

    1. NAME             TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
    2. mysql-80-rhel7   ClusterIP   172.30.63.31   <none>        3306/TCP   4m55s

    By default, the new service does not have an external IP address.

Exposing the service by creating a route

You can expose the service as a route by using the oc expose command.

Procedure

To expose the service:

  1. Log in to OKD.

  2. Log in to the project where the service you want to expose is located:

    1. $ oc project myproject

  3. Run the following command to expose the route:

    1. $ oc expose service <service_name>

    For example:

    1. $ oc expose service mysql-80-rhel7

    Example output

    1. route "mysql-80-rhel7" exposed

  4. Use a tool, such as cURL, to make sure you can reach the service using the cluster IP address for the service:

    1. $ curl <pod_ip>:<port>

    For example:

    1. $ curl 172.30.131.89:3306

    The examples in this section uses a MySQL service, which requires a client application. If you get a string of characters with the Got packets out of order message, you are connected to the service.

    If you have a MySQL client, log in with the standard CLI command:

    1. $ mysql -h 172.30.131.89 -u admin -p

    Example output

    1. Enter password:
    2. Welcome to the MariaDB monitor.  Commands end with ; or \g.
    4. MySQL [(none)]>

Configuring Ingress Controller sharding by using route labels

Ingress Controller sharding by using route labels means that the Ingress Controller serves any route in any namespace that is selected by the route selector.

Ingress Controller sharding is useful when balancing incoming traffic load among a set of Ingress Controllers and when isolating traffic to a specific Ingress Controller. For example, company A goes to one Ingress Controller and company B to another.

Procedure

  1. Edit the router-internal.yaml file:

    1. # cat router-internal.yaml
    2. apiVersion: v1
    3. items:
    4. - apiVersion: operator.openshift.io/v1
    5.   kind: IngressController
    6.   metadata:
    7.     name: sharded
    8.     namespace: openshift-ingress-operator
    9.   spec:
    10.     domain: <apps-sharded.basedomain.example.net>
    11.     nodePlacement:
    12.       nodeSelector:
    13.         matchLabels:
    14.           node-role.kubernetes.io/worker: ""
    15.     routeSelector:
    16.       matchLabels:
    17.         type: sharded
    18.   status: {}
    19. kind: List
    20. metadata:
    21.   resourceVersion: ""
    22.   selfLink: ""

  2. Apply the Ingress Controller router-internal.yaml file:

    1. # oc apply -f router-internal.yaml

    The Ingress Controller selects routes in any namespace that have the label type: sharded.

Configuring Ingress Controller sharding by using namespace labels

Ingress Controller sharding by using namespace labels means that the Ingress Controller serves any route in any namespace that is selected by the namespace selector.

Ingress Controller sharding is useful when balancing incoming traffic load among a set of Ingress Controllers and when isolating traffic to a specific Ingress Controller. For example, company A goes to one Ingress Controller and company B to another.

Procedure

  1. Edit the router-internal.yaml file:

    1. # cat router-internal.yaml

    Example output

    1. apiVersion: v1
    2. items:
    3. - apiVersion: operator.openshift.io/v1
    4.   kind: IngressController
    5.   metadata:
    6.     name: sharded
    7.     namespace: openshift-ingress-operator
    8.   spec:
    9.     domain: <apps-sharded.basedomain.example.net>
    10.     nodePlacement:
    11.       nodeSelector:
    12.         matchLabels:
    13.           node-role.kubernetes.io/worker: ""
    14.     namespaceSelector:
    15.       matchLabels:
    16.         type: sharded
    17.   status: {}
    18. kind: List
    19. metadata:
    20.   resourceVersion: ""
    21.   selfLink: ""

  2. Apply the Ingress Controller router-internal.yaml file:

    1. # oc apply -f router-internal.yaml

    The Ingress Controller selects routes in any namespace that is selected by the namespace selector that have the label type: sharded.

Additional resources