diff --git a/_topic_map.yml b/_topic_map.yml index 1e626302bc76..56c3e6495a64 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/installing/installing_aws/installing-aws-customizations.adoc b/installing/installing_aws/installing-aws-customizations.adoc index 48a64bb0a682..2850984e92a0 100644 --- a/installing/installing_aws/installing-aws-customizations.adoc +++ b/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] diff --git a/installing/installing_aws_user_infra/installing-aws-user-infra.adoc b/installing/installing_aws_user_infra/installing-aws-user-infra.adoc index c650cc18b978..256daf09f436 100644 --- a/installing/installing_aws_user_infra/installing-aws-user-infra.adoc +++ b/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] diff --git a/installing/installing_azure/installing-azure-customizations.adoc b/installing/installing_azure/installing-azure-customizations.adoc index f8a447182ef2..13643465d425 100644 --- a/installing/installing_azure/installing-azure-customizations.adoc +++ b/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] diff --git a/installing/installing_bare_metal/installing-bare-metal.adoc b/installing/installing_bare_metal/installing-bare-metal.adoc index f4d4cb86684f..675524aa5f2c 100644 --- a/installing/installing_bare_metal/installing-bare-metal.adoc +++ b/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"] diff --git a/installing/installing_gcp/installing-gcp-customizations.adoc b/installing/installing_gcp/installing-gcp-customizations.adoc index ca418cd37f13..4a04ae7265f3 100644 --- a/installing/installing_gcp/installing-gcp-customizations.adoc +++ b/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] diff --git a/installing/installing_restricted_networks/installing-disconnected.adoc b/installing/installing_restricted_networks/installing-disconnected.adoc index f8a447182ef2..03ca7222aa13 100644 --- a/installing/installing_restricted_networks/installing-disconnected.adoc +++ b/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] diff --git a/installing/installing_restricted_networks/installing-restricted-networks-aws.adoc b/installing/installing_restricted_networks/installing-restricted-networks-aws.adoc index 6bd8117cc655..46f7f2e71207 100644 --- a/installing/installing_restricted_networks/installing-restricted-networks-aws.adoc +++ b/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] diff --git a/installing/installing_restricted_networks/installing-restricted-networks-bare-metal.adoc b/installing/installing_restricted_networks/installing-restricted-networks-bare-metal.adoc index 68530ffcda15..b2c8723688d1 100644 --- a/installing/installing_restricted_networks/installing-restricted-networks-bare-metal.adoc +++ b/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"] diff --git a/installing/installing_restricted_networks/installing-restricted-networks-vsphere.adoc b/installing/installing_restricted_networks/installing-restricted-networks-vsphere.adoc index 568c995581c2..c207bc4466b7 100644 --- a/installing/installing_restricted_networks/installing-restricted-networks-vsphere.adoc +++ b/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] diff --git a/installing/installing_vsphere/installing-vsphere.adoc b/installing/installing_vsphere/installing-vsphere.adoc index 217d2b1a7f11..19714889adad 100644 --- a/installing/installing_vsphere/installing-vsphere.adoc +++ b/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] diff --git a/modules/installation-configure-proxy.adoc b/modules/installation-configure-proxy.adoc new file mode 100644 index 000000000000..700c98be4855 --- /dev/null +++ b/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://:@: <1> + httpsProxy: http://:@: <2> + noProxy: example.com <3> +additionalTrustBundle: | <4> + -----BEGIN CERTIFICATE----- + + -----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. +==== diff --git a/modules/installation-generate-aws-user-infra-ignition.adoc b/modules/installation-generate-aws-user-infra-ignition.adoc new file mode 100644 index 000000000000..38583e45d7d5 --- /dev/null +++ b/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= <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 ``, 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= <1> +---- +<1> For ``, 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 +---- diff --git a/modules/installation-generate-aws-user-infra-install-config.adoc b/modules/installation-generate-aws-user-infra-install-config.adoc new file mode 100644 index 000000000000..71d29eb7b06a --- /dev/null +++ b/modules/installation-generate-aws-user-infra-install-config.adoc @@ -0,0 +1,121 @@ +// Module included in the following assemblies: +// +// * installing/installing_aws_user_infra/installing-aws-user-infra.adoc + +ifeval::["{context}" == "installing-restricted-networks-aws"] +:restricted: +endif::[] + +[id="installation-generate-aws-user-infra-install-config_{context}"] += Creating the installation configuration file + +Generate and customize the installation configuration file that the +installation program needs to deploy your cluster. + +.Prerequisites + +* Obtain the {product-title} installation program and the pull secret for your +cluster. +ifdef::restricted[] +For a restricted network installation, these files are on your bastion host. +endif::restricted[] + +.Procedure + +. Obtain the `install-config.yaml` file. +.. Run the following command: ++ +---- +$ ./openshift-install create install-config --dir= <1> +---- +<1> For ``, specify the directory name to store the +files that the installation program creates. ++ +[IMPORTANT] +==== +Specify an empty directory. Some installation assets, like bootstrap X.509 +certificates have short expiration intervals, so you must not reuse an +installation directory. If you want to reuse individual files from another +cluster installation, you can copy them into your directory. However, the file +names for the installation assets might change between releases. Use caution +when copying installation files from an earlier {product-title} version. +==== +.. At the prompts, provide the configuration details for your cloud: +... Optional: Select an SSH key to use to access your cluster machines. ++ +[NOTE] +==== +For production {product-title} clusters on which you want to perform installation +debugging or disaster recovery on, you must provide an SSH key that your `ssh-agent` +process uses to the installation program. +==== +... Select *aws* as the platform to target. +... If you do not have an AWS profile stored on your computer, enter the AWS +access key ID and secret access key for the user that you configured to run the +installation program. +... Select the AWS region to deploy the cluster to. +... Select the base domain for the Route53 service that you configured for your cluster. +... Enter a descriptive name for your cluster. +... Paste the pull secret that you obtained from the +link:https://cloud.redhat.com/openshift/install[OpenShift Infrastructure Providers] page. + +. Edit the `install-config.yaml` file to set the number of compute, or worker, +replicas to `0`, as shown in the following `compute` stanza: ++ +[source,yaml] +---- +compute: +- hyperthreading: Enabled + name: worker + platform: {} + replicas: 0 +---- + +ifdef::restricted[] +. Edit the `install-config.yaml` file to provide the additional information that +is required for an installation in a restricted network. +.. Update the `pullSecret` value to contain the authentication information for +your registry: ++ +---- +pullSecret: '{"auths":{":5000": {"auth": "","email": "you@example.com"}}}' +---- ++ +For `bastion_host_name`, specify the registry domain name +that you specified in the certificate for your mirror registry, and for +``, specify the base64-encoded user name and password for +your mirror registry. +.. Add the `additionalTrustBundle` parameter and value: ++ +---- +additionalTrustBundle: | + -----BEGIN CERTIFICATE----- + ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ + -----END CERTIFICATE----- +---- ++ +Provide the contents of the certificate file that you used for your mirror +registry. +.. Update image content resources: ++ +---- +imageContentSources: +- mirrors: + - :5000//release + source: quay.io/openshift-release-dev/ocp-release +- mirrors: + - :5000//release + source: registry.svc.ci.openshift.org/ocp/release +---- ++ +Use the `imageContentSources` section from the output of the command to +mirror the repository. +endif::restricted[] + +. Optional: Back up the `install-config.yaml` file. ++ +[IMPORTANT] +==== +The `install-config.yaml` file is consumed during the installation process. If +you want to reuse the file, you must back it up now. +==== diff --git a/modules/installation-generate-aws-user-infra.adoc b/modules/installation-generate-aws-user-infra.adoc index 316a5031075c..ce01e25fc50d 100644 --- a/modules/installation-generate-aws-user-infra.adoc +++ b/modules/installation-generate-aws-user-infra.adoc @@ -14,170 +14,3 @@ infrastructure, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the `install_config.yaml` file, Kubernetes manifests, and Ignition config files. - -[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 and the pull secret for your cluster. -ifdef::restricted[] -For a restricted network installation, these files are on your bastion host. -endif::restricted[] - -.Procedure - -. Obtain the `install-config.yaml` file. -.. Run the following command: -+ ----- -$ ./openshift-install create install-config --dir= <1> ----- -<1> For ``, specify the directory name to store the -files that the installation program creates. -+ -[IMPORTANT] -==== -Specify an empty directory. Some installation assets, like bootstrap X.509 -certificates have short expiration intervals, so you must not reuse an -installation directory. If you want to reuse individual files from another -cluster installation, you can copy them into your directory. However, the file -names for the installation assets might change between releases. Use caution -when copying installation files from an earlier {product-title} version. -==== -.. At the prompts, provide the configuration details for your cloud: -... Optional: Select an SSH key to use to access your cluster machines. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation -debugging or disaster recovery on, you must provide an SSH key that your `ssh-agent` -process uses to the installation program. -==== -... Select *aws* as the platform to target. -... If you do not have an AWS profile stored on your computer, enter the AWS -access key ID and secret access key for the user that you configured to run the -installation program. -... Select the AWS region to deploy the cluster to. -... Select the base domain for the Route53 service that you configured for your cluster. -... Enter a descriptive name for your cluster. -... Paste the pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install[OpenShift Infrastructure Providers] page. - -. Edit the `install-config.yaml` file to set the number of compute, or worker, -replicas to `0`, as shown in the following `compute` stanza: -+ -[source,yaml] ----- -compute: -- hyperthreading: Enabled - name: worker - platform: {} - replicas: 0 ----- - -ifdef::restricted[] -. Edit the `install-config.yaml` file to provide the additional information that -is required for an installation in a restricted network. -.. Update the `pullSecret` value to contain the authentication information for -your registry: -+ ----- -pullSecret: '{"auths":{":5000": {"auth": "","email": "you@example.com"}}}' ----- -+ -For `bastion_host_name`, specify the registry domain name -that you specified in the certificate for your mirror registry, and for -``, specify the base64-encoded user name and password for -your mirror registry. -.. Add the `additionalTrustBundle` parameter and value: -+ ----- -additionalTrustBundle: | - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- ----- -+ -Provide the contents of the certificate file that you used for your mirror -registry. -.. Update image content resources: -+ ----- -imageContentSources: -- mirrors: - - :5000//release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - :5000//release - source: registry.svc.ci.openshift.org/ocp/release ----- -+ -Use the `imageContentSources` section from the output of the command to -mirror the repository. -endif::restricted[] - -. Optional: Back up the `install-config.yaml` file. -+ -[IMPORTANT] -==== -The `install-config.yaml` file is consumed during the next step. If you want to -reuse the file, back it up now. -==== - -. 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= <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 ``, specify the same installation directory. -+ -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= <1> ----- -<1> For ``, 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 ----- diff --git a/modules/nw-proxy-configure-object.adoc b/modules/nw-proxy-configure-object.adoc index 387f6db5bcc5..c4b652e5d4e9 100644 --- a/modules/nw-proxy-configure-object.adoc +++ b/modules/nw-proxy-configure-object.adoc @@ -81,7 +81,7 @@ metadata: name: cluster spec: httpProxy: http://:@: <1> - httpsProxy: https://:@: <2> + httpsProxy: http://:@: <2> noProxy: example.com <3> readinessEndpoints: - http://www.google.com <4> @@ -89,10 +89,12 @@ spec: trustedCA: name: user-ca-bundle <5> ---- -<1> A proxy URL to use for creating HTTP connections outside the cluster. +<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 is not specified, then `httpProxy` is used for both HTTP and HTTPS -connections. +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.