diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml index 6e2d17766c78..4bed5c3ec4e6 100644 --- a/_topic_maps/_topic_map_osd.yml +++ b/_topic_maps/_topic_map_osd.yml @@ -85,8 +85,6 @@ Name: Tutorials Dir: cloud_experts_osd_tutorials Distros: openshift-dedicated Topics: -- Name: Tutorials overview - File: osd_index - Name: Updating component routes with custom domains and TLS certificates File: cloud-experts-osd-update-component-routes - Name: Limit egress with Google Cloud Next Generation Firewall diff --git a/cloud_experts_osd_tutorials/cloud-experts-osd-create-new-limit-egress.adoc b/cloud_experts_osd_tutorials/cloud-experts-osd-create-new-limit-egress.adoc index 6da389a5e936..8d7323989604 100644 --- a/cloud_experts_osd_tutorials/cloud-experts-osd-create-new-limit-egress.adoc +++ b/cloud_experts_osd_tutorials/cloud-experts-osd-create-new-limit-egress.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: ASSEMBLY [id="cloud-experts-osd-limit-egress-ngfw"] -= Tutorial: Limit egress with Google Cloud Next Generation Firewall += Tutorial: Limiting egress with Google Cloud Next Generation Firewall include::_attributes/attributes-openshift-dedicated.adoc[] :context: cloud-experts-osd-limit-egress-ngfw @@ -8,9 +8,12 @@ include::_attributes/attributes-openshift-dedicated.adoc[] toc::[] [role="_abstract"] -Use this guide to implement egress restrictions for {product-title} on {GCP} by using {GCP}'s Next Generation Firewall (NGFW). NGFW is a fully distributed firewall service that allows fully qualified domain name (FQDN) objects in firewall policy rules. This is necessary for many of the external endpoints that {product-title} relies on. +Implement egress restrictions for {product-title} on {GCP} by using Next Generation Firewall (NGFW), which allows fully qualified domain name (FQDN)-based firewall rules required for {product-title} external endpoints. -include::modules/cloud-experts-osd-limit-egress-ngfw-prereqs.adoc[leveloffset=+1] +[IMPORTANT] +==== +This content is authored by Red{nbsp}Hat experts but has not yet been tested on every supported configuration. +==== include::modules/cloud-experts-osd-limit-egress-ngfw-setup-environ.adoc[leveloffset=+1] @@ -28,5 +31,4 @@ include::modules/cloud-experts-osd-limit-egress-ngfw-create-osd-gcp-cluster.adoc include::modules/cloud-experts-osd-limit-egress-ngfw-delete-osd-gcp-cluster.adoc[leveloffset=+1] -include::modules/cloud-experts-osd-limit-egress-ngfw-clean-resources.adoc[leveloffset=+1] - +include::modules/cloud-experts-osd-limit-egress-ngfw-clean-resources.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc b/cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc index ba4e4569061e..2327847706bd 100644 --- a/cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc +++ b/cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc @@ -8,31 +8,31 @@ include::_attributes/attributes-openshift-dedicated.adoc[] toc::[] [role="_abstract"] -This guide demonstrates how to modify the hostname and TLS certificate of the Web console, OAuth server, and Downloads component routes in {product-title} on {GCP} version 4.14 and above.{fn-supported-versions} - -The changes that we make to the component routes{fn-term-component-routes} in this guide are described in greater detail in the link:https://docs.openshift.com/container-platform/latest/authentication/configuring-internal-oauth.html#customizing-the-oauth-server-url_configuring-internal-oauth[Customing the internal OAuth server URL], link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/web_console/customizing-web-console#customizing-the-console-route_customizing-web-console[Customing the console route], and link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/web_console/customizing-web-console#customizing-the-download-route_customizing-web-console[Customing the download route] {product-title} documentation. - -[id="prerequisites_{context}"] -== Prerequisites -* OCM CLI (`ocm`) version 1.0.5 or higher -* gcloud CLI (`gcloud`) -* An {product-title} on {GCP} cluster version 4.14 or higher -// + -// [NOTE] -// ==== -// ROSA with HCP is not supported at this time. -// ==== -// + -* {oc-first} -* `jq` CLI -* Access to the cluster as a user with the `cluster-admin` role. -* OpenSSL (for generating the demonstration SSL/TLS certificates) +Change the hostname and Transport Layer Security (TLS) certificate of the web console, OAuth server, and Downloads component routes to use custom domains that align with your organization's branding and security requirements. + +[IMPORTANT] +==== +Red Hat experts authored this content, but it has not yet been tested on every supported configuration. +==== include::modules/cloud-experts-osd-update-component-routes-environment-setup.adoc[leveloffset=+1] + include::modules/cloud-experts-osd-update-component-routes-find-current-component-routes.adoc[leveloffset=+1] + include::modules/cloud-experts-osd-update-component-routes-create-tls-certificates.adoc[leveloffset=+1] + include::modules/cloud-experts-osd-update-component-routes-add-certificates-as-secrets.adoc[leveloffset=+1] + include::modules/cloud-experts-osd-update-component-routes-find-lb-hostname.adoc[leveloffset=+1] -include::modules/cloud-experts-osd-update-component-routes-add-component-routes-to-dns.adoc[leveloffset=+1] + include::modules/cloud-experts-osd-update-component-routes-tls-using-ocm-cli.adoc[leveloffset=+1] -include::modules/cloud-experts-osd-update-component-routes-reset-component-routes-to-default.adoc[leveloffset=+1] \ No newline at end of file + +include::modules/cloud-experts-osd-update-component-routes-reset-component-routes-to-default.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/authentication_and_authorization/configuring-internal-oauth#customizing-the-oauth-server-url_configuring-internal-oauth[Customizing the internal OAuth server URL] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/web_console/customizing-web-console#customizing-the-console-route_customizing-web-console[Customizing the console route] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/web_console/customizing-web-console#customizing-the-download-route_customizing-web-console[Customizing the download route] \ No newline at end of file diff --git a/cloud_experts_osd_tutorials/osd_index.adoc b/cloud_experts_osd_tutorials/osd_index.adoc deleted file mode 100644 index 2a6715990ebc..000000000000 --- a/cloud_experts_osd_tutorials/osd_index.adoc +++ /dev/null @@ -1,14 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -[id="osd-tutorials-overview"] -= Tutorials overview - -include::_attributes/attributes-openshift-dedicated.adoc[] -:context: tutorials-overview - -[role="_abstract"] -Use the step-by-step tutorials from Red{nbsp}Hat experts to get the most out of your Managed OpenShift cluster. - -[IMPORTANT] -==== -This content is authored by Red Hat experts but has not yet been tested on every supported configuration. -==== diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-clean-resources.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-clean-resources.adoc index 4f42a31efdfb..8ce585f638c2 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-clean-resources.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-clean-resources.adoc @@ -3,40 +3,37 @@ // * cloud_experts_osd_tutorials/cloud-experts-osd-limit-egress-ngfw.adoc :_mod-docs-content-type: PROCEDURE -[id="cloud-experts-osd-limit-egress-ngfw-clean-resource_{context}"] +[id="cloud-experts-osd-limit-egress-ngfw-clean-resources_{context}"] = Cleaning up resources [role="_abstract"] -To prevent ongoing charges, after you delete your cluster you must manually delete the {GCP} networking infrastructure you created as part of this tutorial. Deleting the cluster will not automatically remove these underlying resources. You can clean up these resources using a combination of gcloud CLI commands and actions within the {GCP} console. - -Before you begin the process of cleaning up the resources you created for this tutorial, run the following commands and complete any prompts. - +Delete the {GCP} networking infrastructure after deleting your cluster to prevent ongoing charges. The cluster deletion does not automatically remove virtual private cloud (VPC) networks, subnets, firewall policies, or domain name system (DNS) zones. .Procedure -. To authenticate your identity run the following command: +. Authenticate by running the following command: + [source,terminal] ---- $ gcloud init ---- + -. To log in to your {GCP} account, run the following command: +. Log in to your {GCP} account by running the following command: + [source,terminal] ---- $ gcloud auth application-default login ---- + -. To log in to the {cluster-manager} CLI tool, run the following command: +. Log in to the {cluster-manager} CLI tool by running the following command: + [source,terminal] ---- $ ocm login --use-auth-code ---- + -You are now ready to clean up the resources you created as part of this tutorial. To respect resource dependencies, delete them in the reverse order of their creation. +You can now clean up the resources you created as part of this tutorial. To respect resource dependencies, delete them in the reverse order of their creation. -. Delete the firewall policy's association with the VPC by running the following command: +. Delete the association of the firewall policy with the VPC by running the following command: + [source,terminal] ---- @@ -53,16 +50,16 @@ $ gcloud compute network-firewall-policies associations delete \ $ gcloud compute network-firewall-policies delete ${prefix} --global ---- + -. A managed DNS zone in {GCP} cannot be deleted until all user-defined record sets are removed. Define variables to target the specific {GCP} project and the managed DNS zone being cleaned up by running the following command: +. You cannot delete a managed DNS zone in {GCP} until you have removed all user-defined record sets. Define variables to target the specific {GCP} project and the managed DNS zone being cleaned up by running the following command: + [source,terminal] ---- $ cat /tmp/delete_records.sh -PROJECT_ID= -ZONE_NAME= +PROJECT_ID= +ZONE_NAME= ---- + -. List the record sets that are included within the Private DNS zone by running the following command: +. List the record sets within the Private DNS zone by running the following command: + [source,terminal] ---- @@ -74,7 +71,7 @@ $ gcloud \ --format="value(name,type)" | while read name type; ---- + -. Delete the record sets that are included within that Private DNS Zone by running the following command: +. Delete the record sets within that Private DNS zone by running the following command: + [source,terminal] ---- @@ -128,7 +125,7 @@ $ gcloud compute networks subnets delete ${prefix}-worker --region=${region} $ gcloud compute networks subnets delete ${prefix}-control-plane --region=${region} ---- + -. Delete the PSC subnet by running the following command: +. Delete the Private Service Connect (PSC) subnet by running the following command: + [source,terminal] ---- @@ -141,3 +138,8 @@ $ gcloud compute networks subnets delete ${prefix}-psc --region=${region} ---- $ gcloud compute networks delete ${prefix}-vpc ---- + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/sdk/gcloud/reference[`gcloud` command-line tool reference ({GCP})] diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-create-a-cloud-router.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-create-a-cloud-router.adoc index 003f82b0b6ea..7087a53e4f1a 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-create-a-cloud-router.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-create-a-cloud-router.adoc @@ -4,15 +4,14 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-limit-egress-ngfw-create-a-cloud-router_{context}"] -= Creating a Cloud Router and a Cloud Network Address Translation gateway += Creating a Cloud Router and Cloud network address translation [role="_abstract"] -The Network Address Translation (NAT) gateway enables internet connectivity for your private VMs by masquerading all their traffic under a single public IP address. As the designated exit point, it translates their internal IPs for any outbound requests, such as fetching updates. This process effectively grants them access to the internet without ever exposing their private addresses. +Create a Cloud Router and Cloud network address translation (NAT). Private VMs can use the internet while their private IP addresses stay hidden. .Procedure . Reserve an IP address for Cloud NAT by running the following command: + - [source,terminal] ---- $ gcloud compute addresses create ${prefix}-${region}-cloudnatip \ @@ -36,4 +35,21 @@ $ gcloud compute routers nats create ${prefix}-cloudnat-${region} \ --router=${prefix}-router --router-region ${region} \ --nat-all-subnet-ip-ranges \ --nat-external-ip-pool=${prefix}-${region}-cloudnatip ----- \ No newline at end of file +---- + +.Verification + +* Check that the Cloud Router and NAT gateway exist by running the following command: ++ +[source,terminal] +---- +$ gcloud compute routers describe ${prefix}-router --region=${region} +---- ++ +The output lists the router and the NAT gateway you created. + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/nat/docs/overview[Cloud NAT overview ({GCP})] +* link:https://cloud.google.com/network-connectivity/docs/router[Cloud Router overview ({GCP})] \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-create-firewall-rules.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-create-firewall-rules.adoc index d665797211c0..fa43d58d2987 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-create-firewall-rules.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-create-firewall-rules.adoc @@ -7,10 +7,10 @@ = Creating the firewall rules [role="_abstract"] -You need to create some firewall rules to allow your cluster to access the Web. +Create firewall rules for egress to private IP ranges and to the {product-title} domains listed in this procedure. Egress to other external destinations does not match these rules and is not permitted. .Procedure -. Create a blanket allow rule for private IP (RFC 1918) address space by running the following command: +. Create a blanket allow rule for private IP (Request for Comments (RFC) 1918) address space by running the following command: + [source,terminal] ---- @@ -42,5 +42,12 @@ $ gcloud compute network-firewall-policies rules create 600 \ + [IMPORTANT] ==== -If there is not a matching rule that allows the traffic, it will be blocked by the firewall. To allow access to other resources, such as internal networks or other external endpoints, create additional rules with a priority of less than 1000. For more information on how to create firewall rules, see link:https://cloud.google.com/firewall/docs/use-network-firewall-policies[Use global network firewall policies and rules]. -==== \ No newline at end of file +The firewall blocks any traffic if you did not create any matching rules. To allow access to other resources, such as internal networks or other external endpoints, create additional rules with a priority of less than 1000. For more information on how to create firewall rules, see the _Additional resources_ in this section. +==== + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/firewall/docs/firewalls[VPC firewall rules overview ({GCP})] +* link:https://docs.redhat.com/en/documentation/openshift_dedicated/4/html/planning_your_environment/gcp-ccs#osd-gcp-psc-firewall-prerequisites_gcp-ccs[Firewall prerequisites for {GCP}] +* link:https://cloud.google.com/firewall/docs/use-network-firewall-policies[Use global network firewall policies and rules] \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-create-osd-gcp-cluster.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-create-osd-gcp-cluster.adoc index 17f82c616afb..fd05eec1f99b 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-create-osd-gcp-cluster.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-create-osd-gcp-cluster.adoc @@ -4,7 +4,9 @@ :_mod-docs-content-type: REFERENCE [id="cloud-experts-osd-limit-egress-ngfw-create-osd-gcp-cluster_{context}"] -= Creating your cluster += Cluster creation [role="_abstract"] -You are now ready to create your {product-title} on {GCP} cluster. For more information, see link:https://docs.redhat.com/en/documentation/openshift_dedicated/4/html/openshift_dedicated_clusters_on_google_cloud/osd-creating-a-cluster-on-gcp-with-workload-identity-federation[Creating a cluster on {GCP} with Workload Identity Federation authentication]. \ No newline at end of file +Your {product-title} cluster on {GCP} uses the VPC, subnets, and firewall rules from this tutorial. + +For detailed instructions on creating a cluster, see link:https://docs.redhat.com/en/documentation/openshift_dedicated/4/html/openshift_dedicated_clusters_on_google_cloud/osd-creating-a-cluster-on-gcp-with-workload-identity-federation[Creating a cluster on {GCP}]. \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-create-private-dns.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-create-private-dns.adoc index dd1d9a6f5596..f6415b4f4f37 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-create-private-dns.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-create-private-dns.adoc @@ -3,11 +3,11 @@ // * cloud_experts_osd_tutorials/cloud-experts-osd-limit-egress-ngfw.adoc :_mod-docs-content-type: PROCEDURE -[id="cloud-experts-osd-limit-egress-ngfw-create-private-DNS_{context}"] +[id="cloud-experts-osd-limit-egress-ngfw-create-private-dns_{context}"] = Creating private Domain Name System records for Private Google Access [role="_abstract"] -The private Domain Name System (DNS) zone optimizes how your resources connect to Google APIs by ensuring traffic never travels over the public internet. It functions by intercepting DNS requests for Google services and resolving them to private IP addresses, forcing the connection onto Google's internal network for a faster, more secure data exchange. +Create a private Domain Name System (DNS) zone to route Google application programming interface (API) traffic through the internal network of Google for faster and more secure connections. .Procedure . Create a private DNS zone for the googleapis.com domain by running the following command: @@ -56,3 +56,20 @@ $ gcloud dns record-sets transaction add 199.36.153.4 199.36.153.5 199.36.153.6 $ gcloud dns record-sets transaction execute \ --zone=$prefix-googleapis ---- + +.Verification + +* Verify the private DNS zone and records were created by running the following command: ++ +[source,terminal] +---- +$ gcloud dns record-sets list --zone=${prefix}-googleapis +---- ++ +The output shows the DNS zone with CNAME and A records for googleapis.com. + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/vpc/docs/configure-private-google-access[Configure Private Google Access ({GCP})] +* link:https://cloud.google.com/dns/docs/zones[DNS zones overview ({GCP})] diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-create-subnets.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-create-subnets.adoc index 0eb739711569..3bb1d0dd3630 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-create-subnets.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-create-subnets.adoc @@ -7,7 +7,7 @@ = Creating the VPC and subnets [role="_abstract"] -Before you can deploy a {GCP} NGFW, you must first create the Virtual Private Cloud (VPC) and subnets that you will use for {product-title}: +Create the Virtual Private Cloud (VPC) and subnets required for deploying {GCP} Next Generation Firewall (NGFW) with {product-title}. .Procedure . Create the VPC by running the following command: @@ -39,7 +39,7 @@ $ gcloud compute networks subnets create ${prefix}-control-plane \ --enable-private-ip-google-access ---- + -. Create the PSC subnets by running the following command: +. Create the Private Service Connect (PSC) subnets by running the following command: + [source,terminal] ---- @@ -52,4 +52,21 @@ $ gcloud compute networks subnets create ${prefix}-psc \ ---- + -These examples use the subnet ranges of 10.0.2.0/23 for the worker subnet, 10.0.0.0/25 for the control plane subnet, and 10.0.0.128/29 for the PSC subnet. Modify the parameters to meet your needs. Ensure the parameter values are contained within the machine CIDR you set earlier in this tutorial. \ No newline at end of file +These examples use the subnet ranges of 10.0.2.0/23 for the worker subnet, 10.0.0.0/25 for the control plane subnet, and 10.0.0.128/29 for the PSC subnet. Modify the parameters to meet your needs. Ensure the parameter values are contained within the machine CIDR you set earlier in this tutorial. + +.Verification + +* Verify the VPC and subnets were created by running the following command: ++ +[source,terminal] +---- +$ gcloud compute networks subnets list --network=${prefix}-vpc +---- ++ +The output shows the three subnets you created with their internet protocol (IP) ranges and regions. + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/vpc/docs/create-modify-vpc-networks[Create and manage VPC networks ({GCP})] +* link:https://cloud.google.com/vpc/docs/subnets[Subnets overview ({GCP})] \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-delete-osd-gcp-cluster.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-delete-osd-gcp-cluster.adoc index 34b0fee9dd34..5ab00a6c1682 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-delete-osd-gcp-cluster.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-delete-osd-gcp-cluster.adoc @@ -4,7 +4,9 @@ :_mod-docs-content-type: REFERENCE [id="cloud-experts-osd-limit-egress-ngfw-delete-osd-gcp-cluster_{context}"] -= Deleting your cluster += Cluster deletion [role="_abstract"] -To delete your cluster, see link:https://docs.redhat.com/en/documentation/openshift_dedicated/4/html/openshift_dedicated_clusters_on_google_cloud/osd-deleting-a-cluster[Deleting an OpenShift Dedicated cluster on {GCP}]. \ No newline at end of file +When you delete your cluster on {GCP}, also clean up the network setup from this guide to prevent ongoing charges. + +For detailed instructions on deleting a cluster, see link:https://docs.redhat.com/en/documentation/openshift_dedicated/4/html/openshift_dedicated_clusters_on_google_cloud/osd-deleting-a-cluster[Deleting an OpenShift Dedicated cluster on {GCP}]. \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-deploy-policy.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-deploy-policy.adoc index 6ce1ffd17c95..3be2c0be8423 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-deploy-policy.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-deploy-policy.adoc @@ -4,13 +4,13 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-limit-egress-ngfw-deploy-policy_{context}"] -= Deploying a global network firewall policy += Deploying a global firewall policy [role="_abstract"] -You can use the `gcloud` CLI tool to create network firewall policies for your cluster. +Create a global network firewall policy. Attach it to your VPC so you can control traffic that leaves your {product-title} cluster. .Procedure -. Create a global network firewall policy by running the following command: +. Run this command to create a global network firewall policy: + [source,terminal] ---- @@ -20,7 +20,7 @@ $ gcloud compute network-firewall-policies create \ --global ---- + -. Associate the newly created global network firewall policy to the VPC you created above by running the following command: +. Run this command to attach the new policy to the VPC you created earlier: + [source,terminal] ---- @@ -28,4 +28,21 @@ $ gcloud compute network-firewall-policies associations create \ --firewall-policy ${prefix} \ --network ${prefix}-vpc \ --global-firewall-policy ----- \ No newline at end of file +---- + +.Verification + +* Run this command to check that the policy exists and is attached to your VPC: ++ +[source,terminal] +---- +$ gcloud compute network-firewall-policies describe ${prefix} --global +---- ++ +The output lists the policy and its link to your VPC. + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/firewall/docs/about-firewalls[Firewall overview ({GCP})] +* link:https://cloud.google.com/firewall/docs/use-network-firewall-policies[Use global network firewall policies and rules ({GCP})] \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-prereqs.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-prereqs.adoc deleted file mode 100644 index 48de9be499a6..000000000000 --- a/modules/cloud-experts-osd-limit-egress-ngfw-prereqs.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * cloud_experts_osd_tutorials/cloud-experts-osd-limit-egress-ngfw.adoc - -:_mod-docs-content-type: CONCEPT -[id="cloud-experts-osd-limit-egress-ngfw-prereqs_{context}"] -= Reviewing your prerequisites - -[role="_abstract"] -The following prerequisites must be met before starting this tutorial. - -* You have the {GCP} Command Line Interface (`gcloud`) installed. -* You are logged into the {GCP} CLI and have selected the {GCP} project where you plan to deploy {product-title}. -* You have the minimum necessary permissions in {GCP}, including: -** `Compute Network Admin` -** `DNS Administrator` - -* You have enabled certain services by running the following commands in your terminal: -+ -[source,terminal] ----- -$ gcloud services enable networksecurity.googleapis.com ----- -+ -[source,terminal] ----- -$ gcloud services enable networkservices.googleapis.com ----- -+ -[source,terminal] ----- -$ gcloud services enable servicenetworking.googleapis.com ----- \ No newline at end of file diff --git a/modules/cloud-experts-osd-limit-egress-ngfw-setup-environ.adoc b/modules/cloud-experts-osd-limit-egress-ngfw-setup-environ.adoc index a676c67ede25..89acd8cdef78 100644 --- a/modules/cloud-experts-osd-limit-egress-ngfw-setup-environ.adoc +++ b/modules/cloud-experts-osd-limit-egress-ngfw-setup-environ.adoc @@ -7,19 +7,44 @@ = Setting up your environment [role="_abstract"] -You can use environment variables to ensure consistency across the commands within this lab. +Set environment variables so each command in this tutorial uses the same values for {product-title} on {GCP} with your firewall rules. + +.Prerequisites +* You have the {GCP} command-line interface (CLI) (`gcloud`) installed. +* You are logged into the {GCP} CLI and have selected the {GCP} project where you plan to deploy {product-title}. +* You have the minimum necessary permissions in {GCP}, including: +** `Compute Network Admin` +** `Domain Name System (DNS) Administrator` +* You enabled the required {GCP} services: +** `networksecurity.googleapis.com` +** `networkservices.googleapis.com` +** `servicenetworking.googleapis.com` ++ +You can enable these services by running the following commands: ++ +[source,terminal] +---- +$ gcloud services enable networksecurity.googleapis.com +$ gcloud services enable networkservices.googleapis.com +$ gcloud services enable servicenetworking.googleapis.com +---- .Procedure -* In your terminal, configure the following environment variables: +* Run this command to set the environment variables: + [source,terminal] ---- -export project_id=$(gcloud config list --format="value(core.project)") -export region=us-east1 -export prefix=osd-ngfw -export service_cidr="172.30.0.0/16" -export machine_cidr="10.0.0.0/22" -export pod_cidr="10.128.0.0/14" +$ export project_id=$(gcloud config list --format="value(core.project)") +$ export region=us-east1 +$ export prefix=osd-ngfw +$ export service_cidr="172.30.0.0/16" +$ export machine_cidr="10.0.0.0/22" +$ export pod_cidr="10.128.0.0/14" ---- + -This example uses `us-east1` as the region to deploy into and the prefix `osd-ngfw` for the cluster's resources. The default CIDR ranges are assigned for the service and pod networks. The machine CIDR is based on the subnet ranges that will be set later in this tutorial. Modify the parameters to meet your needs. \ No newline at end of file +This example sets the region to `us-east1` and the name prefix to `osd-ngfw`. The service and pod networks use the default Classless Inter-Domain Routing (CIDR) ranges in the export list. You add subnet ranges later in this tutorial. The machine CIDR must fit inside those subnet ranges. Change the exports to match your project. + +[role="_additional-resources"] +.Additional resources + +* link:https://cloud.google.com/compute/docs/regions-zones[Regions and zones ({GCP})] \ No newline at end of file diff --git a/modules/cloud-experts-osd-update-component-routes-add-certificates-as-secrets.adoc b/modules/cloud-experts-osd-update-component-routes-add-certificates-as-secrets.adoc index d38635f01536..b200357abb8e 100644 --- a/modules/cloud-experts-osd-update-component-routes-add-certificates-as-secrets.adoc +++ b/modules/cloud-experts-osd-update-component-routes-add-certificates-as-secrets.adoc @@ -7,16 +7,32 @@ = Adding the certificates to the cluster as secrets [role="_abstract"] -You can use the {oc-first} tool to add the certificates to your created cluster as secrets. +Add the Transport Layer Security (TLS) certificates to your cluster as secrets in the `openshift-config` namespace to reference them when updating component routes. .Procedure * Create three TLS secrets in the `openshift-config` namespace. + -These become your secret reference when you update the component routes later in this guide. +These become your secret reference when you update the component routes. + [source,bash] ---- $ oc create secret tls console-tls --cert=cert-console.pem --key=key-console.pem -n openshift-config $ oc create secret tls downloads-tls --cert=cert-downloads.pem --key=key-downloads.pem -n openshift-config $ oc create secret tls oauth-tls --cert=cert-oauth.pem --key=key-oauth.pem -n openshift-config ----- \ No newline at end of file +---- + +.Verification + +* Verify that the TLS secrets were created: ++ +[source,bash] +---- +$ oc get secrets -n openshift-config | grep -E 'console-tls|downloads-tls|oauth-tls' +---- ++ +The output shows the three TLS secrets. + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/nodes/working-with-pods#nodes-pods-secrets-creating_nodes-pods-secrets[Creating secrets] diff --git a/modules/cloud-experts-osd-update-component-routes-add-component-routes-to-dns.adoc b/modules/cloud-experts-osd-update-component-routes-add-component-routes-to-dns.adoc deleted file mode 100644 index e86a86cac80a..000000000000 --- a/modules/cloud-experts-osd-update-component-routes-add-component-routes-to-dns.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc - -:_mod-docs-content-type: CONCEPT -[id="cloud-experts-osd-update-component-routes-add-component-routes-to-dns_{context}"] -= Adding component route DNS records to your hosting provider - -[role="_abstract"] -Create an A record in your DNS settings, pointing the domain to the IP address of the router-default's load balancer. - -//.Need an image for this -//image::[Picture goes here] \ No newline at end of file diff --git a/modules/cloud-experts-osd-update-component-routes-create-tls-certificates.adoc b/modules/cloud-experts-osd-update-component-routes-create-tls-certificates.adoc index c1e1b56494d2..4a2518c1c3a7 100644 --- a/modules/cloud-experts-osd-update-component-routes-create-tls-certificates.adoc +++ b/modules/cloud-experts-osd-update-component-routes-create-tls-certificates.adoc @@ -4,31 +4,59 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-update-component-routes-create-tls-certificates_{context}"] -= Creating a valid TLS certificate for each component route += Creating TLS certificates for each component route [role="_abstract"] -In this section, we create three separate self-signed certificate key pairs and then trust them to verify that we can access our new component routes using a real web browser. +Create three self-signed certificates, one for each component route. Trust them on your system so you can open each new hostname in a browser. [WARNING] ==== -This is for demonstration purposes only, and is not recommended as a solution for production workloads. Consult your certificate authority to understand how to create certificates with similar attributes for your production workloads. +Use this flow for learning only, not for production. For live systems, request valid ceritificates from your certificate authority (CA). ==== [IMPORTANT] ==== -To prevent issues with HTTP/2 connection coalescing, you must use a separate individual certificate for each endpoint. Using a wildcard or SAN certificate is not supported. +Use one certificate per route to prevent issues with HTTP/2 connection coalescing. Wildcard certificates and subject alternative names (SAN) certificates are not supported. ==== -.Procedure -* Generate a certificate for each component route, taking care to set our certificate's subject (`-subj`) to the custom domain of the component route we want to use: +This example uses the following custom component routes: + -*Example*: +* `console.my-new-domain.dev` for Console +* `downloads.my-new-domain.dev` for Downloads +* `oauth.my-new-domain.dev` for OAuth + +.Procedure +* For each route, run the example `openssl` commands. Set `-subj` to that route's domain name: + +.Example output: [source,bash] ---- $ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-console.pem -out cert-console.pem -subj "/CN=console.my-new-domain.dev" $ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-downloads.pem -out cert-downloads.pem -subj "/CN=downloads.my-new-domain.dev" $ openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout key-oauth.pem -out cert-oauth.pem -subj "/CN=oauth.my-new-domain.dev" ---- + +.Verification + +* Check that the `.pem` certificate and key files exist: + -This generates three pairs of `.pem` files, `key-.pem` and `cert-.pem`. \ No newline at end of file +[source,bash] +---- +$ ls -1 *.pem +---- ++ +.Example output +[source,text] +---- +cert-console.pem +cert-downloads.pem +cert-oauth.pem +key-console.pem +key-downloads.pem +key-oauth.pem +---- + +[role="_additional-resources"] +.Additional resources + +* link:https://www.openssl.org/docs/manmaster/man1/openssl-req.html[OpenSSL req command documentation] \ No newline at end of file diff --git a/modules/cloud-experts-osd-update-component-routes-environment-setup.adoc b/modules/cloud-experts-osd-update-component-routes-environment-setup.adoc index 4060d3e88a6c..6e131dcdc513 100644 --- a/modules/cloud-experts-osd-update-component-routes-environment-setup.adoc +++ b/modules/cloud-experts-osd-update-component-routes-environment-setup.adoc @@ -4,10 +4,19 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-update-component-routes-environment-setup_{context}"] -= Setting up your environment += Setting up your environment for component route updates [role="_abstract"] -Before you can update components, you must log in to your cluster as an admin user. +Log in to your cluster as an admin user and configure environment variables to streamline the component route update workflow. + +.Prerequisites +* You have installed {cluster-manager-first} command-line interface (CLI) (`ocm`) version 1.0.5 or higher. +* You have installed `gcloud` CLI. +* You have created an {product-title} on {GCP} cluster version 4.14 or higher. +* You have installed {oc-first}. +* You have installed `jq` CLI. +* You have confirmed that you have access to the cluster as a user with the `cluster-admin` role. +* You have installed OpenSSL (for generating the demonstration SSL/TLS certificates). .Procedure . Log in to your cluster using an account with `cluster-admin` privileges. @@ -19,7 +28,8 @@ Before you can update components, you must log in to your cluster as an admin us $ export CLUSTER_NAME=$(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}$//') ---- -. Ensure all fields output correctly before moving to the next section: +.Verification +* Ensure the environment variable is set correctly: + [source,terminal] ---- @@ -30,4 +40,9 @@ $ echo "Cluster: ${CLUSTER_NAME}" [source,text] ---- Cluster: my-osd-cluster ----- \ No newline at end of file +---- + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_cluster_manager/[{cluster-manager} documentation] diff --git a/modules/cloud-experts-osd-update-component-routes-find-current-component-routes.adoc b/modules/cloud-experts-osd-update-component-routes-find-current-component-routes.adoc index 949c4ab2f01a..6d22d862959d 100644 --- a/modules/cloud-experts-osd-update-component-routes-find-current-component-routes.adoc +++ b/modules/cloud-experts-osd-update-component-routes-find-current-component-routes.adoc @@ -4,10 +4,10 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-update-component-routes-find-current-component-routes_{context}"] -= Find the current routes += Finding the current component routes [role="_abstract"] -You need to use the {oc-first} tool to find the base hostname of your cluster routes. +Find the base hostname of your cluster routes to verify the default component route configuration. .Procedure . Verify that you can reach the component routes on their default hostnames. You can find the hostnames by querying the lists of routes in the `openshift-console` and `openshift-authentication` projects. @@ -28,7 +28,13 @@ NAME HOST/PORT oauth-openshift oauth-openshift.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com ... 1 more oauth-openshift 6443 passthrough/Redirect None ---- + -From this output you can see that our base hostname is `z9a9.p2.openshiftapps.com`. +By running these commands you can see that the default component routes for your cluster are: ++ +* `console-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for Console +* `downloads-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for Downloads +* `oauth-openshift.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for OAuth ++ +From this output you can see that your base hostname is `z9a9.p2.openshiftapps.com`. + . Get the ID of the default ingress by running the following command: + @@ -49,14 +55,8 @@ $ echo "Ingress ID: ${INGRESS_ID}" ---- Ingress ID: r3l6 ---- -+ -By running these commands you can see that the default component routes for our cluster are: -+ -* `console-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for Console -* `downloads-openshift-console.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for Downloads -* `oauth-openshift.apps.my-example-cluster-gcp.z9a9.p2.openshiftapps.com` for OAuth -+ -We can use the `ocm edit ingress` command to change the hostname of each service and add a TLS certificate for all of our component routes. The relevant parameters are shown in this excerpt of the command-line help for the `ocm edit ingress` command: + +. Use the `ocm edit ingress` command to change the hostname of each service and add a TLS certificate for all of your component routes. This excerpt of the command-line help for the `ocm edit ingress` command shows the relevant parameters: + [source,bash] ---- @@ -66,9 +66,8 @@ Edit a cluster ingress for a cluster. Usage: [...] --component-routes string Component routes settings. Available keys [oauth, console, downloads]. For each key a pair of hostname and tlsSecretRef is expected to be supplied. Format should be a comma separate list 'oauth: hostname=example-hostname;tlsSecretRef=example-secret-ref,downloads:...' ---- -+ -For this example, we'll use the following custom component routes: -+ -* `console.my-new-domain.dev` for Console -* `downloads.my-new-domain.dev` for Downloads -* `oauth.my-new-domain.dev` for OAuth \ No newline at end of file + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/web_console/customizing-web-console#customizing-the-console-route_customizing-web-console[Customizing the console route] diff --git a/modules/cloud-experts-osd-update-component-routes-find-lb-hostname.adoc b/modules/cloud-experts-osd-update-component-routes-find-lb-hostname.adoc index aa79ac55f511..1d73cc83d374 100644 --- a/modules/cloud-experts-osd-update-component-routes-find-lb-hostname.adoc +++ b/modules/cloud-experts-osd-update-component-routes-find-lb-hostname.adoc @@ -2,22 +2,37 @@ // // * cloud_experts_osd_tutorials/cloud-experts-osd-update-component-routes.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-update-component-routes-find-lb-hostname_{context}"] -= Finding the load balancer IP of the load balancer in your cluster += Finding the load balancer IP address [role="_abstract"] -When you create a cluster, the service creates a load balancer and generates a load balancer IP for that load balancer. We need to know the load balancer IP in order to create DNS records for our cluster. - -You can find the load balancer IP by running the `oc get svc` command against the `openshift-ingress` namespace. The load balancer IP of the load balancer is the `EXTERNAL-IP` associated with the `router-default` service in the `openshift-ingress` namespace. +Find the load balancer internet protocol (IP) address of your cluster to create domain name system (DNS) records for the component route hostnames. +.Procedure +. Retrieve the IP address of the load balancer by running the following command, using the namespace for the load balancer: ++ +[source,bash] +---- +$ oc get svc -n +---- ++ +The load balancer IP of the load balancer is the `EXTERNAL-IP` associated with the `router-default` service in the `openshift-ingress` namespace. ++ +.Example output [source,bash] ---- $ oc get svc -n openshift-ingress NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE router-default LoadBalancer 172.30.237.88 34.85.169.230 80:31175/TCP,443:31554/TCP 76d ---- ++ +In this example, the load balancer IP is `34.85.169.230`. + +. Save this value for later, as you need it to configure DNS records for your new component route hostnames. +. Create an A record in your DNS settings, pointing the domain to the IP address of the load balancer for router-default. -In our case, the load balancer IP is `34.85.169.230`. +[role="_additional-resources"] +.Additional resources -Save this value for later, as we will need it to configure DNS records for our new component route hostnames. \ No newline at end of file +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/networking_operators/index#nw-ingress-controller-configuration-parameters_configuring-ingress[Ingress controller configuration parameters] \ No newline at end of file diff --git a/modules/cloud-experts-osd-update-component-routes-reset-component-routes-to-default.adoc b/modules/cloud-experts-osd-update-component-routes-reset-component-routes-to-default.adoc index 78c11de9a9c1..24a27e565d3a 100644 --- a/modules/cloud-experts-osd-update-component-routes-reset-component-routes-to-default.adoc +++ b/modules/cloud-experts-osd-update-component-routes-reset-component-routes-to-default.adoc @@ -4,15 +4,25 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-update-component-routes-reset-component-routes-to-default_{context}"] -= Resetting the component routes to the default using the OCM CLI += Resetting routes to defaults [role="_abstract"] -You can use the {oc-first} tool to to reset the component routes to the default configuration. +Reset the routes, use default hostnames, and remove custom TLS certs. .Procedure -* Run the following command to reset your component routes: +* Reset your routes by running the following command: + [source,bash] ---- $ ocm edit ingress -c ${CLUSTER_NAME} ${INGRESS_ID} --component-routes 'console: hostname="";tlsSecretRef="",downloads: hostname="";tlsSecretRef="", oauth: hostname="";tlsSecretRef=""' ----- \ No newline at end of file +---- + +.Verification +* Check that hostnames and TLS cert refs use defaults: ++ +[source,bash] +---- +$ ocm list ingress -c ${CLUSTER_NAME} -ojson | jq ".[] | select(.id == \"${INGRESS_ID}\") | .component_routes" +---- ++ +The output shows empty `hostname` and `tls_secret_ref` for each route. \ No newline at end of file diff --git a/modules/cloud-experts-osd-update-component-routes-tls-using-ocm-cli.adoc b/modules/cloud-experts-osd-update-component-routes-tls-using-ocm-cli.adoc index 49a4ab7ca8ad..e5adbdd90d94 100644 --- a/modules/cloud-experts-osd-update-component-routes-tls-using-ocm-cli.adoc +++ b/modules/cloud-experts-osd-update-component-routes-tls-using-ocm-cli.adoc @@ -4,13 +4,13 @@ :_mod-docs-content-type: PROCEDURE [id="cloud-experts-osd-update-component-routes-tls-using-ocm-cli_{context}"] -= Updating the component routes and TLS secret using the OCM CLI += Updating the component routes and TLS certificates [role="_abstract"] -When your DNS records have been updated, you can use the OCM CLI to change the component routes. +Use the {cluster-manager-first} CLI to apply your custom hostnames and TLS certificates to the component routes. .Procedure -. Use the `ocm edit ingress` command to update your default ingress route with the new base domain and the secret reference associated with it, taking care to update the hostnames for each component route. +. Use the `ocm edit ingress` command to update your default ingress route with the new base domain and the secret reference associated with it, and update the hostnames for each component route. + [source,bash] ---- @@ -26,7 +26,7 @@ $ ocm edit ingress -c ${CLUSTER_NAME} ${INGRESS_ID} --component-routes 'console: ---- ==== + -. Run the `ocm list ingress` command to verify that your changes were successfully made: +. Run the `ocm list ingress` command to verify your changes: + [source,bash] ---- @@ -53,6 +53,4 @@ $ ocm list ingress -c ${CLUSTER_NAME} -ojson | jq ".[] | select(.id == \"${INGRE "tls_secret_ref": "oauth-tls" } } ----- -+ -. Add your certificate to the truststore on your local system, then confirm that you can access your components at their new routes using your local web browser. \ No newline at end of file +---- \ No newline at end of file