[enterprise-4.2] OSDOCS-640: Adding docs for configuring proxy during installation

_topic_map.yml

@@ -161,8 +161,6 @@ Topics:
     Distros: openshift-enterprise,openshift-origin
   - Name: Configuring your firewall
     File: configuring-firewall
-#  - Name: Configuring a custom certificate authority
-#    File: configuring-custom-ca
 ---
 Name: Updating clusters
 Dir: updating

installing/installing_aws/installing-aws-customizations.adoc

@@ -44,6 +44,8 @@ include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 
 include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/installing-aws-customizations.adoc[leveloffset=+1]

installing/installing_aws_user_infra/installing-aws-user-infra.adoc

@@ -50,6 +50,12 @@ include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
 include::modules/installation-generate-aws-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2]
+
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
+include::modules/installation-generate-aws-user-infra-ignition.adoc[leveloffset=+2]
+
 include::modules/installation-extracting-infraid.adoc[leveloffset=+1]
 
 include::modules/installation-creating-aws-vpc.adoc[leveloffset=+1]

installing/installing_azure/installing-azure-customizations.adoc

@@ -32,6 +32,8 @@ include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 
 include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/cli-install.adoc[leveloffset=+1]

installing/installing_bare_metal/installing-bare-metal.adoc

@@ -49,6 +49,8 @@ include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1]
 
 [id="creating-machines-bare-metal"]

installing/installing_gcp/installing-gcp-customizations.adoc

@@ -32,6 +32,8 @@ include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 
 include::modules/installation-gcp-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 //include::modules/installing-aws-customizations.adoc[leveloffset=+1]

installing/installing_restricted_networks/installing-disconnected.adoc

@@ -32,6 +32,9 @@ include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 
 include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 
+// TODO: If this assembly is going to be for restricted network Azure install, whenever it is included, need to confirm whether proxy is supported before including the following file:
+// include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/cli-install.adoc[leveloffset=+1]

installing/installing_restricted_networks/installing-restricted-networks-aws.adoc

@@ -67,8 +67,11 @@ include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
 include::modules/installation-generate-aws-user-infra.adoc[leveloffset=+1]
 
-// After the proxy change merges, I need to put it in and emphasize that you
-// must configure a proxy for the AWS mirrored content story.
+include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2]
+
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
+include::modules/installation-generate-aws-user-infra-ignition.adoc[leveloffset=+2]
 
 include::modules/installation-extracting-infraid.adoc[leveloffset=+1]
 

installing/installing_restricted_networks/installing-restricted-networks-bare-metal.adoc

@@ -59,6 +59,8 @@ include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1]
 
 [id="creating-machines-bare-metal-restricted-network"]

installing/installing_restricted_networks/installing-restricted-networks-vsphere.adoc

@@ -52,6 +52,8 @@ include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-machines.adoc[leveloffset=+1]

installing/installing_vsphere/installing-vsphere.adoc

@@ -40,6 +40,8 @@ include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
 include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-machines.adoc[leveloffset=+1]

modules/installation-configure-proxy.adoc

@@ -0,0 +1,90 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-customizations.adoc
+// * installing/installing_aws_user_infra/installing-aws-user-infra.adoc
+// * installing/installing_bare_metal/installing-bare-metal.adoc
+// * installing/installing_vsphere/installing-vsphere.adoc
+// * installing/installing_gcp/installing-gcp-customizations.adoc
+// * installing/installing_azure/installing-azure-customizations.adoc
+// * installing/installing_restricted_networks/installing-restricted-networks-aws.adoc
+// * installing/installing_restricted_networks/installing-restricted-networks-bare-metal.adoc
+// * installing/installing_restricted_networks/installing-restricted-networks-vsphere.adoc
+
+ifeval::["{context}" == "installing-bare-metal"]
+:bare-metal:
+endif::[]
+
+[id="installation-configure-proxy_{context}"]
+= Configuring the cluster-wide proxy during installation
+
+Production environments can deny direct access to the Internet and instead have
+an HTTP or HTTPS proxy available. You can configure a new {product-title}
+cluster to use a proxy by configuring the proxy settings in the
+`install-config.yaml` file.
+
+ifdef::bare-metal[]
+[NOTE]
+====
+For bare metal installations, if you do not assign node IP addresses from the
+range that is specified in the `networking.machineCIDR` field in the
+`install-config.yaml` file, you must include them in the `proxy.noProxy` field.
+====
+endif::bare-metal[]
+
+.Prerequisites
+
+* An existing `install-config.yaml` file.
+
+.Procedure
+
+. Edit your `install-config.yaml` file and add the proxy settings. For example:
++
+[source,yaml]
+----
+apiVersion: v1
+baseDomain: my.domain.com
+proxy:
+  httpProxy: http://<username>:<pswd>@<ip>:<port> <1>
+  httpsProxy: http://<username>:<pswd>@<ip>:<port> <2>
+  noProxy: example.com <3>
+additionalTrustBundle: | <4>
+    -----BEGIN CERTIFICATE-----
+      <MY_TRUSTED_CA_CERT>
+    -----END CERTIFICATE-----
+...
+----
+<1> A proxy URL to use for creating HTTP connections outside the cluster. The
+URL scheme must be `http`.
+<2> A proxy URL to use for creating HTTPS connections outside the cluster. If
+this field is not specified, then `httpProxy` is used for both HTTP and HTTPS
+connections. The URL scheme must be `http`; `https` is currently not
+supported.
+<3> A comma-separated list of destination domain names, domains, IP addresses, or
+other network CIDRs to exclude proxying. Preface a domain with `.` to include
+all subdomains of that domain. Use `*` to bypass proxy for all destinations.
+<4> If provided, the installation program generates a ConfigMap that is named `user-ca-bundle` in
+the `openshift-config` namespace that contains one or more additional CA
+certificates that are required for proxying HTTPS connections. The Cluster Network
+Operator then creates a `trusted-ca-bundle` ConfigMap that merges these contents
+with the {op-system-first} trust bundle, and this ConfigMap is referenced in the Proxy
+object's `trustedCA` field. The `additionalTrustBundle` field is required unless
+the proxy's identity certificate is signed by an authority from the {op-system} trust
+bundle.
++
+[NOTE]
+====
+The installation program does not support the proxy `readinessEndpoints` field.
+====
+
+. Save the file and reference it when installing {product-title}.
+
+The installation program creates a cluster-wide proxy that is named `cluster` that uses the proxy
+settings in the provided `install-config.yaml` file. If no proxy settings are
+provided, a `cluster` Proxy object is still created, but it will have a nil
+`spec`.
+
+[NOTE]
+====
+Only the Proxy object named `cluster` is supported, and no additional
+proxies can be created.
+====

modules/installation-generate-aws-user-infra-ignition.adoc

@@ -0,0 +1,81 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws_user_infra/installing-aws-user-infra.adoc
+
+[id="installation-generate-aws-user-infra-ignition_{context}"]
+= Creating the Kubernetes manifest and Ignition config files
+
+Because you must manually start the cluster machines, you must generate the
+Kubernetes manifest and Ignition config files that the cluster needs to make its
+machines.
+
+[IMPORTANT]
+====
+The Ignition config files that the installation program generates contain
+certificates that expire after 24 hours. You must complete your cluster
+installation and keep the cluster running for 24 hours in a non-degraded state
+to ensure that the first certificate rotation has finished.
+====
+
+.Prerequisites
+
+* Obtain the {product-title} installation program.
+ifdef::restricted[]
+For a restricted network installation, these files are on your bastion host.
+endif::restricted[]
+* Create the `install-config.yaml` installation configuration file.
+
+.Procedure
+
+. Remove the Kubernetes manifest files for the control plane machines. By
+removing these files, you prevent the cluster from automatically generating
+control plane machines.
+.. Generate the Kubernetes manifests for the cluster:
++
+----
+$ ./openshift-install create manifests --dir=<installation_directory> <1>
+
+WARNING There are no compute nodes specified. The cluster will not fully initialize without compute nodes.
+INFO Consuming "Install Config" from target directory
+----
+<1> For `<installation_directory>`, specify the installation directory that
+contains the `install-config.yaml` file you created.
++
+Because you create your own compute machines later in the installation process,
+you can safely ignore this warning.
+.. Remove the files that define the control plane machines:
++
+----
+$ rm -f openshift/99_openshift-cluster-api_master-machines-*.yaml
+----
+
+ifeval::["{context}" == "installing-aws-user-infra"]
+. Remove the Kubernetes manifest files that define the worker machines:
++
+----
+$ rm -f openshift/99_openshift-cluster-api_worker-machineset-*
+----
++
+Because you create and manage the worker machines yourself, you do not need
+to initialize these machines.
+endif::[]
+
+. Obtain the Ignition config files:
++
+----
+$ ./openshift-install create ignition-configs --dir=<installation_directory> <1>
+----
+<1> For `<installation_directory>`, specify the same installation directory.
++
+The following files are generated in the directory:
++
+----
+.
+├── auth
+│   ├── kubeadmin-password
+│   └── kubeconfig
+├── bootstrap.ign
+├── master.ign
+├── metadata.json
+└── worker.ign
+----