Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OSDOCS-9350-deepdive-3: endpointPublishingStrategy updates #80110

Merged
merged 1 commit into from
Sep 13, 2024
Merged

OSDOCS-9350-deepdive-3: endpointPublishingStrategy updates #80110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1372,9 +1372,6 @@ Topics:
- Name: Configuring the Ingress Controller for manual DNS management
File: ingress-controller-dnsmgt
Distros: openshift-enterprise,openshift-origin
- Name: Configuring the Ingress Controller endpoint publishing strategy
File: nw-configuring-ingress-controller-endpoint-publishing-strategy
Distros: openshift-enterprise,openshift-origin
- Name: Verifying connectivity to an endpoint
File: verifying-connectivity-endpoint
- Name: Changing the cluster network MTU
Expand Down Expand Up @@ -1557,6 +1554,9 @@ Topics:
Distros: openshift-enterprise,openshift-origin
- Name: Configuring ingress cluster traffic using an Ingress Controller
File: configuring-ingress-cluster-traffic-ingress-controller
- Name: Configuring the Ingress Controller endpoint publishing strategy
File: nw-configuring-ingress-controller-endpoint-publishing-strategy
Distros: openshift-enterprise,openshift-origin
- Name: Configuring ingress cluster traffic using a load balancer
File: configuring-ingress-cluster-traffic-load-balancer
Distros: openshift-enterprise,openshift-origin
Expand Down
2 changes: 1 addition & 1 deletion ..._machine_management/cpmso_provider_configurations/cpmso-config-options-aws.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ include::modules/private-clusters-setting-api-private.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources
* xref:../../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingresscontroller-change-internal_configuring-ingress-cluster-traffic-ingress-controller[Configuring the Ingress Controller endpoint publishing scope to Internal]
* xref:../../../networking/configuring_ingress_cluster_traffic/nw-configuring-ingress-controller-endpoint-publishing-strategy.adoc#nw-ingresscontroller-change-internal_nw-configuring-ingress-controller-endpoint-publishing-strategy[Configuring the Ingress Controller endpoint publishing scope to Internal]

//Selecting a larger Amazon Web Services instance type for control plane machines
include::modules/cpms-changing-aws-instance-type.adoc[leveloffset=+2]
Expand Down
2 changes: 1 addition & 1 deletion ...achine_management/cpmso_provider_configurations/cpmso-config-options-azure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ You can enable features by updating values in the control plane machine set.
include::modules/private-clusters-setting-api-private.adoc[leveloffset=+2]
[role="_additional-resources"]
.Additional resources
* xref:../../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingresscontroller-change-internal_configuring-ingress-cluster-traffic-ingress-controller[Configuring the Ingress Controller endpoint publishing scope to Internal]
* xref:../../../networking/configuring_ingress_cluster_traffic/nw-configuring-ingress-controller-endpoint-publishing-strategy.adoc#nw-ingresscontroller-change-internal_nw-configuring-ingress-controller-endpoint-publishing-strategy[Configuring the Ingress Controller endpoint publishing scope to Internal]

//Selecting an Azure Marketplace image
include::modules/installation-azure-marketplace-subscribe.adoc[leveloffset=+2]
Expand Down
2 changes: 1 addition & 1 deletion modules/hcp-virt-wildcard-dns.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[id="hcp-virt-wildcard-dns_{context}"]
= Setting up a wildcard DNS

Set up up a wildcard DNS record or CNAME that references the external IP of the load balancer service.
Set up a wildcard DNS record or CNAME that references the external IP of the load balancer service.

.Procedure

Expand Down
15 changes: 8 additions & 7 deletions modules/nw-creating-project-and-service.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,21 @@
[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 that you want to expose does not exist, create the project and then create the service.

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

.Prerequisites

* Install the `oc` CLI and log in as a cluster administrator.
* Install the {oc-first} and log in as a cluster administrator.

.Procedure

. Create a new project for your service by running the `oc new-project` command:
+
[source,terminal]
----
$ oc new-project myproject
$ oc new-project <project_name>
----

. Use the `oc new-app` command to create your service:
Expand All @@ -36,7 +34,7 @@ $ oc new-app nodejs:12~https://github.com/sclorg/nodejs-ex.git
+
[source,terminal]
----
$ oc get svc -n myproject
$ oc get svc -n <project_name>
----
+
.Example output
Expand All @@ -46,4 +44,7 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nodejs-ex ClusterIP 172.30.197.157 <none> 8080/TCP 70s
----
+
[NOTE]
====
By default, the new service does not have an external IP address.
====
15 changes: 8 additions & 7 deletions modules/nw-exposing-service.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,17 @@ endif::[]

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

.Procedure
.Prerequisites

To expose the service:
* You logged into {product-title}.

. Log in to {product-title}.
.Procedure

. Log in to the project where the service you want to expose is located:
+
[source,terminal]
----
$ oc project myproject
$ oc project <project_name>
----

ifndef::nodeport[]
Expand All @@ -40,9 +40,9 @@ $ oc expose service nodejs-ex
route.route.openshift.io/nodejs-ex exposed
----

. To verify that the service is exposed, you can use a tool, such as cURL, to make sure the service is accessible from outside the cluster.
. To verify that the service is exposed, you can use a tool, such as `curl` to check that the service is accessible from outside the cluster.

.. Use the `oc get route` command to find the route's host name:
.. To find the hostname of the route, enter the following command:
+
[source,terminal]
----
Expand All @@ -56,8 +56,9 @@ NAME HOST/PORT PATH SERVICES PORT TERMI
nodejs-ex nodejs-ex-myproject.example.com nodejs-ex 8080-tcp None
----

.. Use cURL to check that the host responds to a GET request:
.. To check that the host responds to a GET request, enter the following command:
+
.Example `curl` command
[source,terminal]
----
$ curl --head nodejs-ex-myproject.example.com
Expand Down
2 changes: 1 addition & 1 deletion modules/nw-ingress-controller-endpoint-publishing-strategies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// Module included in the following assemblies:
//
// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc
// * networking/nw-configuring-ingress-controller-endpoint-publishing-strategy.adoc

:_mod-docs-content-type: CONCEPT
[id="nw-ingress-controller-endpoint-publishing-strategies_{context}"]
Expand Down
180 changes: 180 additions & 0 deletions modules/nw-ingress-controller-nodeportservice-projects.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
// Module included in the following assemblies:
//
// * networking/configuring_ingress_cluster_traffic/nw-configuring-ingress-controller-endpoint-publishing-strategy.adoc

:_mod-docs-content-type: PROCEDURE
[id="nw-ingress-controller-nodeportservice-projects_{context}"]
= Adding a single NodePort service to an Ingress Controller

Instead of creating a `NodePort`-type `Service` for each project, you can create a custom Ingress Controller to use the `NodePortService` endpoint publishing strategy. To prevent port conflicts, consider this configuration for your Ingress Controller when you want to apply a set of routes, through Ingress sharding, to nodes that might already have a `HostNetwork` Ingress Controller.

Before you set a `NodePort`-type `Service` for each project, read the following considerations:

* You must create a wildcard DNS record for the Nodeport Ingress Controller domain. A Nodeport Ingress Controller route can be reached from the address of a worker node. For more information about the required DNS records for routes, see "User-provisioned DNS requirements".
* You must expose a route for your service and specify the `--hostname` argument for your custom Ingress Controller domain.
* You must append the port that is assigned to the `NodePort`-type `Service` in the route so that you can access application pods.

.Prerequisites

* You installed the {oc-first}.
* Logged in as a user with `cluster-admin` privileges.
* You created a wildcard DNS record.
// https://docs.openshift.com/container-platform/4.16/networking/ingress-controller-dnsmgt.html (does not detail how to create the DNS)
dfitzmau marked this conversation as resolved.
Show resolved Hide resolved

.Procedure

. Create a custom resource (CR) file for the Ingress Controller:
+
.Example of a CR file that defines information for the `IngressController` object
[source,yaml]
----
apiVersion: v1
items:
- apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
name: <custom_ic_name> <1>
namespace: openshift-ingress-operator
spec:
replicas: 1
domain: <custom_ic_domain_name> <2>
nodePlacement:
nodeSelector:
matchLabels:
<key>: <value> <3>
namespaceSelector:
matchLabels:
<key>: <value> <4>
endpointPublishingStrategy:
type: NodePortService
# ...
----
Copy link

@lihongan lihongan Sep 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We just create one custom ingresscontroller here so better not use kind: List, this part can be updated as

apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
  name: <custom_ic_name> <1>
  namespace: openshift-ingress-operator
spec:
  replicas: 1
  domain: <custom_ic_domain_name> <2>
  nodePlacement:
    nodeSelector:
      matchLabels:
        <key>: <value> <3>
  namespaceSelector:
    matchLabels:
      <key>: <value> <4>
  endpointPublishingStrategy:
    type: NodePortService

<1> Specify the a custom `name` for the `IngressController` CR.
<2> The DNS name that the Ingress Controller services. As an example, the default ingresscontroller domain is `apps.ipi-cluster.example.com`, so you would specify the `<custom_ic_domain_name>` as `nodeportsvc.ipi-cluster.example.com`.
<3> Specify the label for the nodes that include the custom Ingress Controller.
<4> Specify the label for a set of namespaces. Substitute `<key>:<value>` with a map of key-value pairs where `<key>` is a unique name for the new label and `<value>` is its value. For example: `ingresscontroller: custom-ic`.

. Add a label to a node by using the `oc label node` command:
dfitzmau marked this conversation as resolved.
Show resolved Hide resolved
+
[source,terminal]
----
$ oc label node <node_name> <key>=<value> <1>
----
<1> Where `<value>` must match the key-value pair specified in the `nodePlacement` section of your `IngressController` CR.

. Create the `IngressController` object:
+
[source,terminal]
----
$ oc create -f <ingress_controller_cr>.yaml
----

. Find the port for the service created for the `IngressController` CR:
+
[source,terminal]
----
$ oc get svc -n openshift-ingress
----
+
.Example output that shows port `80:32432/TCP` for the `router-nodeport-custom-ic3` service
[source,terminal]
----
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
router-internal-default ClusterIP 172.30.195.74 <none> 80/TCP,443/TCP,1936/TCP 223d
router-nodeport-custom-ic3 NodePort 172.30.109.219 <none> 80:32432/TCP,443:31366/TCP,1936:30499/TCP 155m
----

. To create a new project, enter the following command:
+
[source,terminal]
----
$ oc new-project <project_name>
----

. To label the new namespace, enter the following command:
+
[source,terminal]
----
$ oc label namespace <project_name> <key>=<value> <1>
----
<1> Where `<key>=<value>` must match the value in the `namespaceSelector` section of your Ingress Controller CR.

. Create a new application in your cluster:
+
[source,terminal]
----
$ oc new-app --image=<image_name> <1>
----
<1> An example of `<image_name>` is `quay.io/openshifttest/hello-openshift:multiarch`.

. Create a `Route` object for a service, so that the pod can use the service to expose the application external to the cluster.
+
[source,terminal]
----
$ oc expose svc/<service_name> --hostname=<svc_name>-<project_name>.<custom_ic_domain_name> <1>
----
+
[NOTE]
====
You must specify the domain name of your custom Ingress Controller in the `--hostname` argument. If you do not do this, the Ingress Operator uses the default Ingress Controller to serve all the routes for your cluster.
====

dfitzmau marked this conversation as resolved.
Show resolved Hide resolved
. Check that the route has the `Admitted` status and that it includes metadata for the custom Ingress Controller:
+
[source,terminal,subs="quotes,attributes"]
----
$ oc get route/hello-openshift -o json | jq '.status.ingress'
----
+
.Example output
[source,terminal]
----
# ...
{
"conditions": [
{
"lastTransitionTime": "2024-05-17T18:25:41Z",
"status": "True",
"type": "Admitted"
}
],
[
{
"host": "hello-openshift.nodeportsvc.ipi-cluster.example.com",
"routerCanonicalHostname": "router-nodeportsvc.nodeportsvc.ipi-cluster.example.com",
"routerName": "nodeportsvc", "wildcardPolicy": "None"
}
],
}
----

. Update the default `IngressController` CR to prevent the default Ingress Controller from managing the `NodePort`-type `Service`. The default Ingress Controller will continue to monitor all other cluster traffic.
+
[source,terminal]
----
$ oc patch --type=merge -n openshift-ingress-operator ingresscontroller/default --patch '{"spec":{"namespaceSelector":{"matchExpressions":[{"key":"<key>","operator":"NotIn","values":["<value>]}]}}}'
----

.Verification

. Verify that the DNS entry can route inside and outside of your cluster by entering the following command. The command outputs the IP address of the node that received the label from running the `oc label node` command earlier in the procedure.
+
[source,terminal]
----
$ dig +short <svc_name>-<project_name>.<custom_ic_domain_name>
----

. To verify that your cluster uses the IP addresses from external DNS servers for DNS resolution, check the connection of your cluster by entering the following command:
+
[source,terminal]
----
$ curl <svc_name>-<project_name>.<custom_ic_domain_name>:<port> <1>
----
<1> Where `<port>` is the node port from the `NodePort`-type `Service`. Based on example output from the `oc get svc -n openshift-ingress` command, the `80:32432/TCP` HTTP route means that `32432` is the node port.
+
.Output example
+
[source,terminal]
----
Hello OpenShift!
----
19 changes: 1 addition & 18 deletions ...ess_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ 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
* You 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
Expand All @@ -45,9 +45,7 @@ include::modules/nw-creating-project-and-service.adoc[leveloffset=+1]
// Exposing the service by creating a route
include::modules/nw-exposing-service.adoc[leveloffset=+1]

// Router sharding
ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]

// Ingress sharding in OpenShift Container Platform
include::modules/nw-ingress-sharding-concept.adoc[leveloffset=+1]

Expand Down Expand Up @@ -89,18 +87,3 @@ include::modules/nw-ingress-sharding-route-configuration.adoc[leveloffset=+2]

* xref:../../networking/network_security/network_policy/about-network-policy.adoc#about-network-policy[About network policy]
endif::openshift-enterprise,openshift-webscale,openshift-origin[]

// Ingress Controller endpoint publishing strategy
include::modules/nw-ingress-controller-endpoint-publishing-strategies.adoc[leveloffset=+1]

// Configuring the Ingress Controller endpoint publishing scope to Internal
include::modules/nw-ingresscontroller-change-internal.adoc[leveloffset=+2]

// Configuring the Ingress Controller endpoint publishing scope to External
include::modules/nw-ingresscontroller-change-external.adoc[leveloffset=+2]

[discrete]
[id="additional-resources_nw-ingress-controller-endpoint-publishing-strategies"]
=== Additional resources

* xref:../networking/ingress-operator#nw-ingress-controller-configuration-parameters_configuring-ingress[Ingress Controller configuration parameters]
7 changes: 5 additions & 2 deletions ...uring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
:_mod-docs-content-type: ASSEMBLY
[id="configuring-ingress-cluster-traffic-nodeport"]
= Configuring ingress cluster traffic using a NodePort
= Configuring ingress cluster traffic by using a NodePort
include::_attributes/common-attributes.adoc[]
:context: configuring-ingress-cluster-traffic-nodeport

Expand Down Expand Up @@ -38,13 +38,16 @@ 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
include::modules/nw-creating-project-and-service.adoc[leveloffset=+1]

// Exposing the service by creating a route
include::modules/nw-exposing-service.adoc[leveloffset=+1]


[role="_additional-resources"]
[id="configuring-ingress-cluster-traffic-nodeport-additional-resources"]
== Additional resources

* xref:../../networking/configuring-node-port-service-range.adoc#configuring-node-port-service-range[Configuring the node port service range]

* xref:../../networking/configuring_ingress_cluster_traffic/nw-configuring-ingress-controller-endpoint-publishing-strategy.adoc#nw-ingress-controller-nodeportservice-projects_nw-configuring-ingress-controller-endpoint-publishing-strategy[Adding a single NodePort service to an Ingress Controller]
Loading