openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

osdocs-354 getting traffic into cluster

Browse Source
This commit is contained in:
bmcelvee
2019-04-29 15:42:30 -04:00
committed by openshift-cherrypick-robot
parent f8ae305e09
commit 30b2868168
24 changed files with 571 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
_topic_map.yml
View File

@@ -285,6 +285,19 @@ Topics:
File: route-configuration
- Name: Secured routes
File: secured-routes
- Name: Configuring ingress cluster traffic
Dir: configuring-ingress-cluster-traffic
Topics:
- Name: Overview
File: overview-traffic
- Name: Configuring ingress cluster traffic using an Ingress Controller
File: configuring-ingress-cluster-traffic-ingress-controller
- Name: Configuring ingress cluster traffic using a load balancer
File: configuring-ingress-cluster-traffic-load-balancer
- Name: Configuring ingress cluster traffic using a service external IP
File: configuring-ingress-cluster-traffic-service-external-ip
- Name: Configuring ingress cluster traffic using a NodePort
File: configuring-ingress-cluster-traffic-nodeport
---
Name: Storage
Dir: storage

2
modules/customize-certificates-replace-default-router.adoc
View File

@@ -34,7 +34,7 @@ local file system.
<3> `</path/to/cert.key>` is the path to the private key associated
with this certificate.
. Update the ingress controller configuration with the newly created
. Update the Ingress Controller configuration with the newly created
secret:
+
----

2
modules/nw-configuring-route-timeouts.adoc
View File

@@ -11,7 +11,7 @@ Availability (SLA) purposes, or a high timeout, for cases with a slow
back end.
.Prerequisites
* You need a deployed Ingress controller on a running cluster.
* You need a deployed Ingress Controller on a running cluster.
.Procedure
. Using the `oc annotate` command, add the timeout to the route:

103
modules/nw-create-load-balancer-service.adoc Normal file
View File

@@ -0,0 +1,103 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-create-load-balancer-service_{context}"]
= Creating a load balancer service
Use the following procedure to create a load balancer service.
.Prerequisites
* Make sure that the project and service you want to expose exist.
.Procedure
To create a load balancer service:
. Log into {product-title}.
. Load the project where the service you want to expose is located.
+
----
$ oc project project1
----
. Open a text file on the master node and paste the following text, editing the
file as needed:
+
.Sample load balancer configuration file
====
----
apiVersion: v1
kind: Service
metadata:
name: egress-2 <1>
spec:
ports:
- name: db
port: 3306 <2>
loadBalancerIP:
type: LoadBalancer <3>
selector:
name: mysql <4>
----
<1> Enter a descriptive name for the load balancer service.
<2> Enter the same port that the service you want to expose is listening on.
<3> Enter `loadbalancer` as the type.
<4> Enter the name of the service.
====
. Save and exit the file.
. Run the following command to create the service:
+
----
oc create -f <file-name>
----
+
For example:
+
----
oc create -f mysql-lb.yaml
----
. Execute the following command to view the new service:
+
----
$ oc get svc -n openshift-ingress
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
router-default LoadBalancer 172.30.16.119 52.230.228.163 80:30745/TCP,443:32561/TCP 2d6h
router-internal-default ClusterIP 172.30.101.15 <none> 80/TCP,443/TCP,1936/TCP 2d6h
----
+
The service has an external IP address automatically assigned if there is a cloud
provider enabled.
. On the master, use a tool, such as cURL, to make sure you can reach the service
using the public IP address:
+
----
$ curl <public-ip>:<port>
----
++
For example:
+
----
$ curl 172.29.121.74:3306
----
+
The examples in this section use 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 connecting with the service:
+
If you have a MySQL client, log in with the standard CLI command:
+
----
$ mysql -h 172.30.131.89 -u admin -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
MySQL [(none)]>
----

49
modules/nw-creating-project-and-service.adoc Normal file
View File

@@ -0,0 +1,49 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-creating-project-and-service_{context}"]
= 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, go to the next step:
*Exposing the service to create a route*.
. Log into {product-title}.
. Create a new project for your service:
+
----
$ oc new-project <project_name>
----
+
For example:
+
----
$ oc new-project <myproject>
----
. Use the `oc new-app` command to create a service:
+
For example:
+
----
$ oc new-app \
-e MYSQL_USER=admin \
-e MYSQL_PASSWORD=redhat \
-e MYSQL_DATABASE=mysqldb \
registry.redhat.io/openshift3/mysql-55-rhel7
----
. Run the following command to see that the new service is created:
+
----
$ oc get svc -n openshift-ingress
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
router-default LoadBalancer 172.30.16.119 52.230.228.163 80:30745/TCP,443:32561/TCP 2d6h
router-internal-default ClusterIP 172.30.101.15 <none> 80/TCP,443/TCP,1936/TCP 2d6h
----
+
By default, the new service does not have an external IP address.

62
modules/nw-exposing-service.adoc Normal file
View File

@@ -0,0 +1,62 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-exposing-service_{context}"]
= Exposing the service by creating a route
You can expose the service as a route using the `oc expose` command.
To expose the service:
. Log into {product-title}.
. Log into the project where the service you want to expose is located.
+
----
$ oc project project1
----
. Run the following command to expose the route:
+
----
oc expose service <service-name>
----
+
For example:
+
----
oc expose service mysql-55-rhel7
route "mysql-55-rhel7" exposed
----
. Use a tool, such as cURL, to make sure you can reach the
service using the cluster IP address for the service:
+
----
curl <pod-ip>:<port>
----
+
For example:
+
----
curl 172.30.131.89:3306
----
+
The examples in this section use 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:
+
----
$ mysql -h 172.30.131.89 -u admin -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
MySQL [(none)]>
----
//Potentially add verification step, "If a verification step is needed, it would
//look something like oc get route mysql-55-rhel7 and curl with the host from the
//output of the oc get route command."

6
modules/nw-ingress-controller-status.adoc
View File

@@ -3,13 +3,13 @@
// * ingress/configure-ingress-operator.adoc
[id="nw-ingress-controller-status_{context}"]
= View Ingress controller status
= View Ingress Controller status
Your can view the status of a particular Ingress controller.
Your can view the status of a particular Ingress Controller.
.Procedure
* View the status of an Ingress controller:
* View the status of an Ingress Controller:
+
----
$ oc describe --namespace=openshift-ingress-operator ingresscontroller/<name>

2
modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc
View File

@@ -34,7 +34,7 @@ $ openssl rsa -in password_protected_tls.key -out tls.key
This procedure creates a `Route` resource with a custom certificate and
reencrypt TLS termination. The following assumes that the certificate/key pair
are in the `tls.crt` and `tls.key` files in the current working directory. You
must also specify a destination CA certificate to enable the Ingress controller
must also specify a destination CA certificate to enable the Ingress Controller
to trust the service's certificate. You may also specify a CA certificate if
needed to complete the certificate chain. Substitute the actual path names for
`tls.crt`, `tls.key`, `cacert.crt`, and (optionally) `ca.crt`. Substitute the

4
modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc
View File

@@ -7,9 +7,9 @@
You can configure a secure route using edge TLS termination with a custom
certificate by using the `oc create route` command. With an edge route, the
ingress controller terminates TLS encryption before forwarding traffic to the
Ingress Controller terminates TLS encryption before forwarding traffic to the
destination Pod. The route specifies the TLS certificate and key that the
ingress controller uses for the route.
Ingress Controller uses for the route.
.Prerequisites

6
modules/nw-ingress-operator-logs.adoc
View File

@@ -3,13 +3,13 @@
// * ingress/configure-ingress-operator.adoc
[id="nw-ingress-operator-logs_{context}"]
= View Ingress controller logs
= View Ingress Controller logs
You can view your Ingress controller logs.
You can view your Ingress Controller logs.
.Procedure
* View your Ingress controller logs:
* View your Ingress Controller logs:
+
----
$ oc logs --namespace=openshift-ingress-operator deployments/ingress-operator

6
modules/nw-ingress-setting-a-custom-default-certificate.adoc
View File

@@ -5,7 +5,7 @@
[id="nw-ingress-setting-a-custom-default-certificate_{context}"]
= Setting a custom default certificate
As an administrator, you can configure an Ingress controller to use a custom
As an administrator, you can configure an Ingress Controller to use a custom
certificate by creating a `Secret` resource and editing the `IngressController`
custom resource (CR).
@@ -33,7 +33,7 @@ referencing it in the `IngressController` CR.
[NOTE]
====
This action will cause the Ingress controller to be redeployed, using a rolling deployment strategy.
This action will cause the Ingress Controller to be redeployed, using a rolling deployment strategy.
====
. Create a `Secret` resource containing the custom certificate in the
@@ -65,4 +65,4 @@ map[name:custom-certs-default]
The certificate secret name should match the value used to update the CR.
Once the `IngressController` CR has been modified, the Ingress Operator
will update the Ingress controller's deployment to use the custom certificate.
will update the Ingress Controller's deployment to use the custom certificate.

6
modules/nw-ingress-view.adoc
View File

@@ -3,19 +3,19 @@
// * ingress/configure-ingress-operator.adoc
[id="nw-ingress-view_{context}"]
= View the default Ingress controller
= View the default Ingress Controller
The Ingress Operator is a core feature of {product-title} and is enabled out of the
box.
Every new {product-title} installation has an `ingresscontroller` named default. It
can be supplemented with additional Ingress controllers. If the default
can be supplemented with additional Ingress Controllers. If the default
`ingresscontroller` is deleted, the Ingress Operator will automatically recreate it
within a minute.
.Procedure
* View the default Ingress controller:
* View the default Ingress Controller:
+
----
$ oc describe --namespace=openshift-ingress-operator ingresscontroller/default

2
modules/nw-installation-ingress-config-asset.adoc
View File

@@ -26,7 +26,7 @@ the `manifests/` directory. This `Ingress` resource defines the cluster-wide
configuration for Ingress. This Ingress configuration is used as follows:
* The Ingress Operator uses the domain from the cluster Ingress configuration as
the domain for the default Ingress controller.
the domain for the default Ingress Controller.
* The OpenShift API server operator uses the domain from the cluster Ingress
configuration as the domain used when generating a default host for a `Route`

4
modules/nw-scaling-ingress-controller.adoc
View File

@@ -3,9 +3,9 @@
// * networking/ingress-controller-configuration.adoc
[id="nw-ingress-controller-configuration_{context}"]
= Scaling an Ingress controller
= Scaling an Ingress Controller
An Ingress controller can be manually scaled up or down based on
An Ingress Controller can be manually scaled up or down based on
requirements such as the requirement to increase throughput. `oc`
commands are used to scale the `IngressController` resource.
The following procedure provides an example for scaling up the

2
modules/nw-using-cookies-keep-route-statefulness.adoc
View File

@@ -17,5 +17,5 @@ this statefulness can disappear.
controller selects an endpoint to handle any user requests, and creates a cookie
for the session. The cookie is passed back in the response to the request and
the user sends the cookie back with the next request in the session. The cookie
tells the Ingress controller which endpoint is handling the session, ensuring
tells the Ingress Controller which endpoint is handling the session, ensuring
that client requests use the cookie so that they are routed to the same Pod.

41
modules/nw-using-ingress-and-routes.adoc Normal file
View File

@@ -0,0 +1,41 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-using-ingress-and-routes_{context}"]
= 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 {product-title} 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.
When a set of routes is created in various projects, the overall set of routes
is available to the set of Ingress Controllers. Each Ingress Controller admits
routes from the set of routes. By default, all Ingress Controllers
admit all routes.
Ingress Controllers that have permission to view all of the labels in all
projects can select routes to admit based on the labels. This is called Ingress
Controller sharding. This 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.
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.

19
modules/nw-using-load-balancer-getting-traffic.adoc Normal file
View File

@@ -0,0 +1,19 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-using-load-balancer-getting-traffic_{context}"]
= Using a load balancer to get traffic into the cluster
If you do not need a specific external IP address, you can configure a load
balancer service to allow external access to an {product-title} cluster.
A load balancer service allocates a unique IP. The load balancer has a single
edge router IP, which can be a virtual IP (VIP), but is still a single machine
for initial load balancing.
[NOTE]
====
If a pool is configured, it is done at the infrastructure level, not by a cluster
administrator.
====

25
modules/nw-using-nodeport.adoc Normal file
View File

@@ -0,0 +1,25 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-using-nodeport_{context}"]
= Using a NodePort to get traffic into the cluster
Use a `NodePort`-type `Service` resource to expose a service on a specific port
on all nodes in the cluster. The port is specified in the `Service` resource's
`.spec.ports[*].nodePort` field.
[NOTE]
====
Using `NodePort`s requires additional port resources.
====
A node port exposes the service on a static port on the node IP address.
`NodePort`s are in the `30000-32767` range by default, which means a `NodePort` is
unlikely to match a service’s intended port. For example, `8080` may be exposed
as `31020`.
The administrator must ensure the external IPs are routed to the nodes.
`NodePort`s and external IPs are independent and both can be used concurrently.

23
modules/nw-using-service-external-ip.adoc Normal file
View File

@@ -0,0 +1,23 @@
// Module included in the following assemblies:
//
// * ingress/getting-traffic-cluster.adoc
[id="nw-service-external-ip_{context}"]
= Using a service external IP to get traffic into the cluster
One method to expose a service is to assign an external IP address directly to
the service you want to make accessible from outside the cluster.
The external IP address that you use must be provisioned on your infrastructure
platform and attached to a cluster node.
With an external IP on the service, {product-title} sets up sets up NAT rules to
allow traffic arriving at any cluster node attached to that IP address to be
sent to one of the internal pods. This is similar to the internal
service IP addresses, but the external IP tells {product-title} that this
service should also be exposed externally at the given IP. The administrator
must assign the IP address to a host (node) interface on one of the nodes in the
cluster. Alternatively, the address can be used as a virtual IP (VIP).
These IPs are not managed by {product-title} and administrators are
responsible for ensuring that traffic arrives at a node with this IP.

51
networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc Normal file
View File

@@ -0,0 +1,51 @@
[id="configuring-ingress-cluster-traffic-ingress-controller"]
= Configuring ingress cluster traffic using an Ingress Controller
include::modules/common-attributes.adoc[]
:context: configuring-ingress-cluster-traffic-ingress-controller
toc::[]
{product-title} provides methods for communicating from outside the cluster with
services running in the cluster. This method uses an Ingress Controller.
include::modules/nw-using-ingress-and-routes.adoc[leveloffset=+1]
[NOTE]
====
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:
+
----
oc adm policy add-cluster-role-to-user cluster-admin username
----
* Have an {product-title} 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.
include::modules/nw-creating-project-and-service.adoc[leveloffset=+1]
include::modules/nw-exposing-service.adoc[leveloffset=+1]
== Additional resources
* The Ingress Operator manages wildcard DNS. For more information, see
xref:../../networking/ingress-operator.adoc#configuring-ingress[Ingress Operator
in {product-title}],
xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Installing
a cluster on bare metal], and
xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Installing a cluster on vSphere].

44
networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-load-balancer.adoc Normal file
View File

@@ -0,0 +1,44 @@
[id="configuring-ingress-cluster-traffic-load-balancer"]
= Configuring ingress cluster traffic using a load balancer
include::modules/common-attributes.adoc[]
:context: configuring-ingress-cluster-traffic-load-balancer
toc::[]
{product-title} provides methods for communicating from
outside the cluster with services running in the cluster. This method uses a
load balancer.
include::modules/nw-using-load-balancer-getting-traffic.adoc[leveloffset=+1]
[NOTE]
====
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:
+
----
oc adm policy add-cluster-role-to-user cluster-admin username
----
* Have an {product-title} 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.
include::modules/nw-creating-project-and-service.adoc[leveloffset=+1]
include::modules/nw-exposing-service.adoc[leveloffset=+1]
include::modules/nw-create-load-balancer-service.adoc[leveloffset=+1]

43
networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-nodeport.adoc Normal file
View File

@@ -0,0 +1,43 @@
[id="configuring-ingress-cluster-traffic-nodeport"]
= Configuring ingress cluster traffic using a NodePort
include::modules/common-attributes.adoc[]
:context: configuring-ingress-cluster-traffic-nodeport
toc::[]
{product-title} provides methods for communicating from
outside the cluster with services running in the cluster. This method uses a
`NodePort`.
include::modules/nw-using-nodeport.adoc[leveloffset=+1]
[NOTE]
====
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:
+
----
oc adm policy add-cluster-role-to-user cluster-admin username
----
* Have an {product-title} 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.
include::modules/nw-creating-project-and-service.adoc[leveloffset=+1]
include::modules/nw-exposing-service.adoc[leveloffset=+1]

42
networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc Normal file
View File

@@ -0,0 +1,42 @@
[id="configuring-ingress-cluster-traffic-service-external-ip"]
= Configuring ingress cluster traffic using a service external IP
include::modules/common-attributes.adoc[]
:context: configuring-ingress-cluster-traffic-service-external-ip
toc::[]
{product-title} provides methods for communicating from
outside the cluster with services running in the cluster. This method uses a
service external IP.
include::modules/nw-using-service-external-ip.adoc[leveloffset=+1]
[NOTE]
====
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:
+
----
oc adm policy add-cluster-role-to-user cluster-admin username
----
* Have an {product-title} 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.
include::modules/nw-creating-project-and-service.adoc[leveloffset=+1]
include::modules/nw-exposing-service.adoc[leveloffset=+1]

35
networking/configuring-ingress-cluster-traffic/overview-traffic.adoc Normal file
View File

@@ -0,0 +1,35 @@
[id="overview-traffic"]
= Configuring ingress cluster traffic overview
include::modules/common-attributes.adoc[]
:context: overview-traffic
toc::[]
{product-title} provides the following methods for communicating from
outside the cluster with services running in the cluster.
The methods are recommended, in order or preference:
* If you have HTTP/HTTPS, use an Ingress Controller.
* If you have a TLS-encrypted protocol other than HTTPS. For example, for TLS
with the SNI header, use an Ingress Controller.
* Otherwise, use a Load Balancer, an External IP, or a `NodePort`.
[[external-access-options-table]]
[options="header"]
|===
|Method |Purpose
|xref:../../networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#configuring-ingress-cluster-traffic-ingress-controller[Use an Ingress Controller]
|Allows access to HTTP/HTTPS traffic and TLS-encrypted protocols other than HTTPS (for example, TLS with the SNI header).
|xref:../../networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-load-balancer.adoc#configuring-ingress-cluster-traffic-load-balancer[Automatically assign an external IP using a load balancer service]
|Allows traffic to non-standard ports through an IP address assigned from a pool.
|xref:../../networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc#configuring-ingress-cluster-traffic-service-external-ip[Manually assign an external IP to a service]
|Allows traffic to non-standard ports through a specific IP address.
|xref:../../networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-nodeport.adoc#configuring-ingress-cluster-traffic-nodeport[Configure a `NodePort`]
|Expose a service on all nodes in the cluster.
|===