<commit_before>[id="planning-migration-3-to-4"]
= Planning your migration
include::modules/common-attributes.adoc[]
:context: planning-migration-3-to-4

toc::[]

Before performing your migration to {product-title} 4.2, it is important to take the time to properly plan for the transition. {product-title} 4 introduces architectural changes and enhancements, so the procedures that you used to manage your {product-title} 3 cluster might not apply for {product-title} 4.

[NOTE]
====
This planning document assumes that you are transitioning from {product-title} 3.11 to {product-title} 4.2.
====

This document provides high-level information on the most important xref:../migration/planning-migration-3-to-4.adoc#migration-comparing-ocp-3-4[differences between {product-title} 3 and {product-title} 4] and the most noteworthy xref:../migration/planning-migration-3-to-4.adoc#migration-considerations[migration considerations]. For detailed information on configuring your {product-title} 4 cluster, review the appropriate sections of the {product-title} documentation. For detailed information on new features and other notable technical changes, review the xref:../release_notes/ocp-4-2-release-notes.adoc#ocp-4-2-release-notes[OpenShift Container Platform 4.2 release notes].

It is not possible to upgrade your existing {product-title} 3 cluster to {product-title} 4. You must start with a new {product-title} 4 installation. Tools are available to assist in migrating your control plane settings and application workloads.

[id="migration-comparing-ocp-3-4"]
== Comparing {product-title} 3 and {product-title} 4

With {product-title} 3, administrators individually deployed Red Hat Enterprise Linux (RHEL) hosts, and then installed {product-title} on top of these hosts to form a cluster. Administrators were responsible for properly configuring these hosts and performing updates.

{product-title} 4 represents a significant change in the way that {product-title} clusters are deployed and managed. {product-title} 4 includes new technologies and functionality, such as Operators, MachineSets, and {op-system-first}, which are core to the operation of the cluster. This technology shift enables clusters to self-manage some functions previously performed by administrators. This also ensures platform stability and consistency, and simplifies installation and scaling.

For more information, see xref:../architecture/architecture.adoc#architecture[OpenShift Container Platform architecture].

[id="migration-differences-archictecture"]
=== Architecture differences

[discrete]
==== Immutable infrastructure

{product-title} 4 uses {op-system-first}, which is designed to run containerized applications, and provides efficient installation, Operator-based management, and simplified upgrades. {op-system} is an immutable container host, rather than a customizable operating system like RHEL. {op-system} enables {product-title} 4 to manage and automate the deployment of the underlying container host. {op-system} is a part of {product-title}, which means that everything runs inside a container and is deployed using {product-title}.

In {product-title} 4, control plane nodes must run {op-system}, ensuring that full-stack automation is maintained for the control plane. This makes rolling out updates and upgrades a much easier process than in {product-title} 3.

For more information, see xref:../architecture/architecture-rhcos.adoc#architecture-rhcos[Red Hat Enterprise Linux CoreOS].

[discrete]
==== Operators

Operators are a method of packaging, deploying, and managing a Kubernetes application. Operators ease the operational complexity of running another piece of software. They watch over your environment and use the current state to make decisions in real time. Advanced Operators are designed to upgrade and react to failures automatically.

For more information, see xref:../operators/olm-what-operators-are.adoc#olm-what-operators-are[Understanding Operators].

[id="migration-differences-install"]
=== Installation and update differences

[discrete]
==== Installation process

To install {product-title} 3.11, you prepared your Red Hat Enterprise Linux (RHEL) hosts, set all of the configuration values your cluster needed, and then ran an Ansible playbook to install and set up your cluster.

In {product-title} 4.2, you use the OpenShift installation program to create a minimum set of resources required for a cluster. Once the cluster is running, you use Operators to further configure your cluster and to install new services. After first boot, {op-system-first} systems are managed by the Machine Config Operator (MCO) that runs in the {product-title} cluster.

For more information, see xref:../architecture/architecture-installation.adoc#installation-process_architecture-installation[Installation process].

If you want to add RHEL worker machines to your {product-title} 4.2 cluster, you use an Ansible playbook to join the RHEL worker machines after the cluster is running. For more information, see xref:../machine_management/adding-rhel-compute.adoc#adding-rhel-compute[Adding RHEL compute machines to an {product-title} cluster].

[discrete]
==== Infrastructure options

In {product-title} 3.11, you installed your cluster on infrastructure that you prepared and maintained. In addition to providing your own infrastructure, {product-title} 4 offers an option to deploy a cluster on infrastructure that the {product-title} installation program provisions and the cluster maintains.

For more information, see xref:../architecture/architecture-installation.adoc#installation-overview_architecture-installation[OpenShift Container Platform installation overview].

[discrete]
==== Upgrading your cluster

In {product-title} 3.11, you upgraded your cluster by running Ansible playbooks. In {product-title} 4.2, The cluster manages its own updates, including updates to {op-system-first} on cluster nodes. You can easily upgrade your cluster by using the web console or by using the `oc adm upgrade` command from the OpenShift CLI and the Operators will automatically upgrade themselves. If your {product-title} 4.2 cluster has Red Hat Enterprise Linux worker machines, then you will still need to run an Ansible playbook to upgrade those worker machines.

For more information, see xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating clusters].

[id="migration-considerations"]
== Migration considerations

Review the changes and other considerations that might affect your transition from {product-title} 3.11 to {product-title} 4.

[id="migration-preparing-storage"]
=== Storage considerations

Review the following storage changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Local volume persistent storage

Local storage is only supported by using the Local Storage Operator in {product-title} 4.2. It is not supported to use the local provisioner method from {product-title} 3.11.

For more information, see xref:../storage/persistent-storage/persistent-storage-local.adoc#persistent-storage-using-local-volume[Persistent storage using local volumes].

////
// TODO: Removing until Support confirms

[discrete]
==== FlexVolume persistent storage

The FlexVolume plug-in location changed from {product-title} 3.11. The new location in {product-title} 4.2 is `/etc/kubernetes/kubelet-plugins/volume/exec`. Attachable FlexVolume plug-ins are no longer supported.

// TODO: No FlexVolume docs in 4.2 to link to right now.

////

[discrete]
==== Container Storage Interface (CSI) persistent storage

Persistent storage using the Container Storage Interface (CSI) was link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] in {product-title} 3.11. CSI version 1.1.0 is fully supported in {product-title} 4.2, but does not ship with any CSI drivers. You must install your own driver.

For more information, see xref:../storage/persistent-storage/persistent-storage-csi.adoc#persistent-storage-using-csi[Persistent storage using the Container Storage Interface (CSI)].

[discrete]
==== Unsupported persistent storage options

Support for the following persistent storage options from {product-title} 3.11 has changed in {product-title} 4.2:

* GlusterFS is no longer supported.
* CephFS is no longer supported.
* Ceph RBD is no longer supported.
// TODO: Removing until Support confirms
// * iSCSI is now Technology Preview.

If you used of one these in {product-title} 3.11, you must choose a different persistent storage option for full support in {product-title} 4.2.

For more information, see xref:../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage].

// TODO: OCS 4.x not out yet, consider adding OCS 3.x -> OCS 4.x here once it is.

[id="migration-preparing-networking"]
=== Networking considerations

Review the following networking changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Network isolation mode

The default network isolation mode for {product-title} 3.11 was `ovs-subnet`, though users frequently switched to use `ovn-multitenant`. The default network isolation mode for {product-title} 4.2 is now NetworkPolicy.

If your {product-title} 3.11 cluster used the `ovs-subnet` or `ovs-multitenant` mode, it is recommended to switch to the NetworkPolicy mode for your {product-title} 4.2 cluster. NetworkPolicy is supported upstream, is more flexible, and also provides the functionality that `ovs-multitenant` does. If you want to maintain the `ovs-multitenant` behavior while using NetworkPolicy in {product-title} 4.2, follow the steps to xref:../networking/configuring-networkpolicy.adoc#nw-networkpolicy-multitenant-isolation_configuring-networkpolicy-plugin[configure multitenant isolation using NetworkPolicy].

For more information, see xref:../networking/configuring-networkpolicy.adoc#nw-networkpolicy-about_configuring-networkpolicy-plugin[About network policy].

[discrete]
==== Encrypting traffic between hosts

In {product-title} 3.11, you could use IPsec to encrypt traffic between hosts. {product-title} 4.2 does not support IPsec. It is recommended to use Red Hat OpenShift Service Mesh to enable mutual TLS between services.

For more information, see xref:../service_mesh/service_mesh_arch/understanding-ossm.adoc#understanding-ossm[Understanding Red Hat OpenShift Service Mesh].

[id="migration-preparing-logging"]
=== Logging considerations

Review the following logging changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Deploying cluster logging

{product-title} 4 provides a simple deployment mechanism for cluster logging, by using a Cluster Logging custom resource. Once deployed, the cluster logging experience is the same as it was in {product-title} 3.11.

For more information, see xref:../logging/cluster-logging-deploying-about.adoc#cluster-logging-deploying-about_cluster-logging-deploying-about[About deploying and configuring cluster logging].

[discrete]
==== Aggregated logging data

You cannot transition your aggregate logging data from {product-title} 3.11 into your new {product-title} 4 cluster.

For more information, see xref:../logging/cluster-logging.adoc#cluster-logging-about_cluster-logging[About cluster logging].

[id="migration-preparing-security"]
=== Security considerations

Review the following security changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Unauthenticated access to discovery endpoints

In {product-title} 3.11, an unauthenticated user could access the discovery endpoints (for example, [x-]`/api/*` and [x-]`/apis/*`). For security reasons, unauthenticated access to the discovery endpoints is no longer allowed in {product-title} 4.2. If you do need to allow unauthenticated access, you can configure the RBAC settings as necessary; however, be sure to consider the security implications as this can expose internal cluster components to the external network.

// TODO: Anything to xref to, or additional details?

[discrete]
==== Identity providers

Configuration for identity providers has changed for {product-title} 4, including the following notable changes:

* The request header identity provider in {product-title} 4.2 requires mutual TLS, where in {product-title} 3.11 it did not.
* The configuration of the OpenID Connect identity provider was simplified in {product-title} 4.2. It now obtains data, which previously had to specified in {product-title} 3.11, from the provider's `/.well-known/openid-configuration` endpoint.

For more information, see xref:../authentication/understanding-identity-provider.adoc#understanding-identity-provider[Understanding identity provider configuration].

[id="migration-preparing-monitoring"]
=== Monitoring considerations

Review the following monitoring changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Alert for monitoring infrastructure availability

The default alert that triggers to ensure the availability of the monitoring structure was called `DeadMansSwitch` in {product-title} 3.11. This was renamed to `Watchdog` in {product-title} 4. If you had PagerDuty integration set up with this alert in {product-title} 3.11, you must set up the PagerDuty integration for the `Watchdog` alert in {product-title} 4.

For more information, see xref:../monitoring/cluster-monitoring/configuring-the-monitoring-stack.adoc#applying-custom-alertmanager-configuration_configuring-monitoring[Applying custom Alertmanager configuration].
<commit_msg>Commenting out link to 4.2 notes for 4.3<commit_after>[id="planning-migration-3-to-4"]
= Planning your migration
include::modules/common-attributes.adoc[]
:context: planning-migration-3-to-4

toc::[]

Before performing your migration to {product-title} 4.2, it is important to take the time to properly plan for the transition. {product-title} 4 introduces architectural changes and enhancements, so the procedures that you used to manage your {product-title} 3 cluster might not apply for {product-title} 4.

[NOTE]
====
This planning document assumes that you are transitioning from {product-title} 3.11 to {product-title} 4.2.
====

This document provides high-level information on the most important xref:../migration/planning-migration-3-to-4.adoc#migration-comparing-ocp-3-4[differences between {product-title} 3 and {product-title} 4] and the most noteworthy xref:../migration/planning-migration-3-to-4.adoc#migration-considerations[migration considerations]. For detailed information on configuring your {product-title} 4 cluster, review the appropriate sections of the {product-title} documentation.

// TODO: Link to 4.3 release notes
// For detailed information on new features and other notable technical changes, review the xref:../release_notes/ocp-4-2-release-notes.adoc#ocp-4-2-release-notes[OpenShift Container Platform 4.2 release notes].

It is not possible to upgrade your existing {product-title} 3 cluster to {product-title} 4. You must start with a new {product-title} 4 installation. Tools are available to assist in migrating your control plane settings and application workloads.

[id="migration-comparing-ocp-3-4"]
== Comparing {product-title} 3 and {product-title} 4

With {product-title} 3, administrators individually deployed Red Hat Enterprise Linux (RHEL) hosts, and then installed {product-title} on top of these hosts to form a cluster. Administrators were responsible for properly configuring these hosts and performing updates.

{product-title} 4 represents a significant change in the way that {product-title} clusters are deployed and managed. {product-title} 4 includes new technologies and functionality, such as Operators, MachineSets, and {op-system-first}, which are core to the operation of the cluster. This technology shift enables clusters to self-manage some functions previously performed by administrators. This also ensures platform stability and consistency, and simplifies installation and scaling.

For more information, see xref:../architecture/architecture.adoc#architecture[OpenShift Container Platform architecture].

[id="migration-differences-archictecture"]
=== Architecture differences

[discrete]
==== Immutable infrastructure

{product-title} 4 uses {op-system-first}, which is designed to run containerized applications, and provides efficient installation, Operator-based management, and simplified upgrades. {op-system} is an immutable container host, rather than a customizable operating system like RHEL. {op-system} enables {product-title} 4 to manage and automate the deployment of the underlying container host. {op-system} is a part of {product-title}, which means that everything runs inside a container and is deployed using {product-title}.

In {product-title} 4, control plane nodes must run {op-system}, ensuring that full-stack automation is maintained for the control plane. This makes rolling out updates and upgrades a much easier process than in {product-title} 3.

For more information, see xref:../architecture/architecture-rhcos.adoc#architecture-rhcos[Red Hat Enterprise Linux CoreOS].

[discrete]
==== Operators

Operators are a method of packaging, deploying, and managing a Kubernetes application. Operators ease the operational complexity of running another piece of software. They watch over your environment and use the current state to make decisions in real time. Advanced Operators are designed to upgrade and react to failures automatically.

For more information, see xref:../operators/olm-what-operators-are.adoc#olm-what-operators-are[Understanding Operators].

[id="migration-differences-install"]
=== Installation and update differences

[discrete]
==== Installation process

To install {product-title} 3.11, you prepared your Red Hat Enterprise Linux (RHEL) hosts, set all of the configuration values your cluster needed, and then ran an Ansible playbook to install and set up your cluster.

In {product-title} 4.2, you use the OpenShift installation program to create a minimum set of resources required for a cluster. Once the cluster is running, you use Operators to further configure your cluster and to install new services. After first boot, {op-system-first} systems are managed by the Machine Config Operator (MCO) that runs in the {product-title} cluster.

For more information, see xref:../architecture/architecture-installation.adoc#installation-process_architecture-installation[Installation process].

If you want to add RHEL worker machines to your {product-title} 4.2 cluster, you use an Ansible playbook to join the RHEL worker machines after the cluster is running. For more information, see xref:../machine_management/adding-rhel-compute.adoc#adding-rhel-compute[Adding RHEL compute machines to an {product-title} cluster].

[discrete]
==== Infrastructure options

In {product-title} 3.11, you installed your cluster on infrastructure that you prepared and maintained. In addition to providing your own infrastructure, {product-title} 4 offers an option to deploy a cluster on infrastructure that the {product-title} installation program provisions and the cluster maintains.

For more information, see xref:../architecture/architecture-installation.adoc#installation-overview_architecture-installation[OpenShift Container Platform installation overview].

[discrete]
==== Upgrading your cluster

In {product-title} 3.11, you upgraded your cluster by running Ansible playbooks. In {product-title} 4.2, The cluster manages its own updates, including updates to {op-system-first} on cluster nodes. You can easily upgrade your cluster by using the web console or by using the `oc adm upgrade` command from the OpenShift CLI and the Operators will automatically upgrade themselves. If your {product-title} 4.2 cluster has Red Hat Enterprise Linux worker machines, then you will still need to run an Ansible playbook to upgrade those worker machines.

For more information, see xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating clusters].

[id="migration-considerations"]
== Migration considerations

Review the changes and other considerations that might affect your transition from {product-title} 3.11 to {product-title} 4.

[id="migration-preparing-storage"]
=== Storage considerations

Review the following storage changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Local volume persistent storage

Local storage is only supported by using the Local Storage Operator in {product-title} 4.2. It is not supported to use the local provisioner method from {product-title} 3.11.

For more information, see xref:../storage/persistent-storage/persistent-storage-local.adoc#persistent-storage-using-local-volume[Persistent storage using local volumes].

////
// TODO: Removing until Support confirms

[discrete]
==== FlexVolume persistent storage

The FlexVolume plug-in location changed from {product-title} 3.11. The new location in {product-title} 4.2 is `/etc/kubernetes/kubelet-plugins/volume/exec`. Attachable FlexVolume plug-ins are no longer supported.

// TODO: No FlexVolume docs in 4.2 to link to right now.

////

[discrete]
==== Container Storage Interface (CSI) persistent storage

Persistent storage using the Container Storage Interface (CSI) was link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] in {product-title} 3.11. CSI version 1.1.0 is fully supported in {product-title} 4.2, but does not ship with any CSI drivers. You must install your own driver.

For more information, see xref:../storage/persistent-storage/persistent-storage-csi.adoc#persistent-storage-using-csi[Persistent storage using the Container Storage Interface (CSI)].

[discrete]
==== Unsupported persistent storage options

Support for the following persistent storage options from {product-title} 3.11 has changed in {product-title} 4.2:

* GlusterFS is no longer supported.
* CephFS is no longer supported.
* Ceph RBD is no longer supported.
// TODO: Removing until Support confirms
// * iSCSI is now Technology Preview.

If you used of one these in {product-title} 3.11, you must choose a different persistent storage option for full support in {product-title} 4.2.

For more information, see xref:../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage].

// TODO: OCS 4.x not out yet, consider adding OCS 3.x -> OCS 4.x here once it is.

[id="migration-preparing-networking"]
=== Networking considerations

Review the following networking changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Network isolation mode

The default network isolation mode for {product-title} 3.11 was `ovs-subnet`, though users frequently switched to use `ovn-multitenant`. The default network isolation mode for {product-title} 4.2 is now NetworkPolicy.

If your {product-title} 3.11 cluster used the `ovs-subnet` or `ovs-multitenant` mode, it is recommended to switch to the NetworkPolicy mode for your {product-title} 4.2 cluster. NetworkPolicy is supported upstream, is more flexible, and also provides the functionality that `ovs-multitenant` does. If you want to maintain the `ovs-multitenant` behavior while using NetworkPolicy in {product-title} 4.2, follow the steps to xref:../networking/configuring-networkpolicy.adoc#nw-networkpolicy-multitenant-isolation_configuring-networkpolicy-plugin[configure multitenant isolation using NetworkPolicy].

For more information, see xref:../networking/configuring-networkpolicy.adoc#nw-networkpolicy-about_configuring-networkpolicy-plugin[About network policy].

[discrete]
==== Encrypting traffic between hosts

In {product-title} 3.11, you could use IPsec to encrypt traffic between hosts. {product-title} 4.2 does not support IPsec. It is recommended to use Red Hat OpenShift Service Mesh to enable mutual TLS between services.

For more information, see xref:../service_mesh/service_mesh_arch/understanding-ossm.adoc#understanding-ossm[Understanding Red Hat OpenShift Service Mesh].

[id="migration-preparing-logging"]
=== Logging considerations

Review the following logging changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Deploying cluster logging

{product-title} 4 provides a simple deployment mechanism for cluster logging, by using a Cluster Logging custom resource. Once deployed, the cluster logging experience is the same as it was in {product-title} 3.11.

For more information, see xref:../logging/cluster-logging-deploying-about.adoc#cluster-logging-deploying-about_cluster-logging-deploying-about[About deploying and configuring cluster logging].

[discrete]
==== Aggregated logging data

You cannot transition your aggregate logging data from {product-title} 3.11 into your new {product-title} 4 cluster.

For more information, see xref:../logging/cluster-logging.adoc#cluster-logging-about_cluster-logging[About cluster logging].

[id="migration-preparing-security"]
=== Security considerations

Review the following security changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Unauthenticated access to discovery endpoints

In {product-title} 3.11, an unauthenticated user could access the discovery endpoints (for example, [x-]`/api/*` and [x-]`/apis/*`). For security reasons, unauthenticated access to the discovery endpoints is no longer allowed in {product-title} 4.2. If you do need to allow unauthenticated access, you can configure the RBAC settings as necessary; however, be sure to consider the security implications as this can expose internal cluster components to the external network.

// TODO: Anything to xref to, or additional details?

[discrete]
==== Identity providers

Configuration for identity providers has changed for {product-title} 4, including the following notable changes:

* The request header identity provider in {product-title} 4.2 requires mutual TLS, where in {product-title} 3.11 it did not.
* The configuration of the OpenID Connect identity provider was simplified in {product-title} 4.2. It now obtains data, which previously had to specified in {product-title} 3.11, from the provider's `/.well-known/openid-configuration` endpoint.

For more information, see xref:../authentication/understanding-identity-provider.adoc#understanding-identity-provider[Understanding identity provider configuration].

[id="migration-preparing-monitoring"]
=== Monitoring considerations

Review the following monitoring changes to consider when transitioning from {product-title} 3.11 to {product-title} 4.2.

[discrete]
==== Alert for monitoring infrastructure availability

The default alert that triggers to ensure the availability of the monitoring structure was called `DeadMansSwitch` in {product-title} 3.11. This was renamed to `Watchdog` in {product-title} 4. If you had PagerDuty integration set up with this alert in {product-title} 3.11, you must set up the PagerDuty integration for the `Watchdog` alert in {product-title} 4.

For more information, see xref:../monitoring/cluster-monitoring/configuring-the-monitoring-stack.adoc#applying-custom-alertmanager-configuration_configuring-monitoring[Applying custom Alertmanager configuration].

{'fraction_non_alphanumeric': 0.08216389151457863, 'fraction_numerical': 0.012724496473496692, 'mean_word_length': 5.243077621425329, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3092858', 'n_tokens_mistral': 7396, 'n_tokens_neox': 6904, 'n_words': 3085}