openshift-docs/rosa_hcp/rosa-hcp-egress-zero-install.adoc

:_mod-docs-content-type: ASSEMBLY
[id="rosa-hcp-egress-zero-install"]
= Creating {egress-zero-title}
include::_attributes/attributes-openshift-dedicated.adoc[]
:context: rosa-hcp-egress-zero-install
toc::[]

Creating {product-title} with {egress-zero} provides a way to enhance your cluster's stability and security by allowing your cluster to use the image registry in the local region if the cluster cannot access the internet. Your cluster first tries to pull the images from Quay, and when they aren't reached, it instead pulls the images from the image registry in the local region. 

All public and private clusters with {egress-zero} get their Red{nbsp}Hat container images from an Amazon Elastic Container Registry (ECR) located in the local region of the cluster instead of gathering these images from various endpoints and registries on the internet. ECR provides storage for OpenShift release images as well as Red{nbsp}Hat Operators. All requests for ECR are kept within your AWS network by serving them over a VPC endpoint within your cluster.

{egress-zero-title} use AWS ECR to provision your clusters without the need for public internet. Because necessary cluster lifecycle processes occur over AWS private networking, AWS ECR serves as a critical service for core cluster platform images. For more information on AWS ECR, see link:https://aws.amazon.com/ecr/[Amazon Elastic Container Registry].

You can create a fully operational cluster that does not require a public egress by configuring a virtual private cloud (VPC) and using the `--properties zero_egress:true` flag when creating your cluster.

See xref:../upgrading/rosa-hcp-upgrading.adoc#rosa-hcp-upgrading[Upgrading {product-title} clusters] to upgrade clusters using {egress-zero}. 

[NOTE]
====
Clusters created in restricted network environments may be unable to use certain ROSA features including Red Hat Insights and Telemetry. These clusters may also experience potential failures for workloads that require public access to registries such as `quay.io`. When using clusters installed with {egress-zero}, you can also install Red Hat-owned Operators from OperatorHub. For a complete list of Red Hat-owned Operators, see the link:https://catalog.redhat.com/search?searchType=software&target_platforms=Red%20Hat%20OpenShift&deployed_as=Operator&p=1&partnerName=Red%20Hat%2C%20Inc.%7CRed%20Hat[Red{nbsp}Hat Ecosystem Catalog]. Only the default Operator channel is mirrored for any Operator that is installed with {egress-zero}.
====

[discrete]
[id="rosa-glossary-disconnected_{context}"]
== Glossary of network environment terms

Although it is used throughout the {product-title} documentation, _disconnected environment_ is a broad term that can refer to environments with various levels of internet connectivity.
Other terms are sometimes used to refer to a specific level of internet connectivity, and these environments might require additional unique configurations. These network types differ from a "standard network," which has full access to the internet.

The following table describes the different terms used to refer to environments without a full internet connection:

.Disconnected environment terms
[cols=".^2,.^4",options="header"]
|====
|Term |Description

|Air-gapped network
|An environment or network that is completely isolated from an external network.

This isolation depends on a physical separation, or an "air gap", between machines on the internal network and any part of an external network.
Air-gapped environments are often used in industries with strict security or regulatory requirements.

|Disconnected environment
|An environment or network that has some level of isolation from an external network.

This isolation could be enabled by physical or logical separation between machines on the internal network and an external network.
Regardless of the level of isolation from the external network, a cluster in a disconnected environment does not have access to public services hosted by Red{nbsp}Hat and requires additional setup to maintain full cluster functionality.

|Restricted network
|An environment or network with limited connection to an external network.

A physical connection might exist between machines on the internal network and an external network, but network traffic is limited by additional configurations, such as firewalls and proxies.
|====

.Prequisites

* You have an AWS account with sufficient permissions to create VPCs, subnets, and other required infrastructure.
* You have installed the Terraform v1.4.0+ CLI.
* You have installed the ROSA v1.2.45+ CLI.
* You have installed and configured the AWS CLI with the necessary credentials.
* You have installed the git CLI.

[IMPORTANT]
====
* You can use {egress-zero} on all supported versions of {product-title} that use the hosted control plane architecture; however, Red{nbsp}Hat suggests using the latest available z-stream release for each {ocp} version. 

* While you may install and upgrade your clusters as you would a regular cluster, due to an upstream issue with how the internal image registry functions in disconnected environments, your cluster that uses {egress-zero} will not be able to fully use all platform components, such as the image registry. You can restore these features by using the latest ROSA version when upgrading or installing your cluster.
====

include::modules/rosa-hcp-set-environment-variables.adoc[leveloffset=+1]

[id="rosa-hcp-egress-zero-install-creating_{context}"]
== Creating a Virtual Private Cloud for your {product-title} clusters 

You must have a Virtual Private Cloud (VPC) to create a {product-title} cluster. To pull images from the local ECR mirror over your VPC endpoint, you must configure a privatelink service connection and modify the default security groups with specific tags. Use one of the following methods to create a VPC:

* Create a VPC using the ROSA command-line interface (CLI)
* Create a VPC by using a Terraform template
* Create a VPC using the AWS CLI
* Manually create the VPC resources in the AWS console

include::modules/rosa-hcp-create-network.adoc[leveloffset=+2]
include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+2]

[id="rosa-hcp-vpc-aws_{context}"]
=== Creating a VPC using the AWS CLI

You can create a VPC by using the AWS CLI. For information on using this CLI, see the link:https://docs.aws.amazon.com/cli/latest/reference/ec2/create-vpc.html[AWS create-vpc documentation].

include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2]
include::snippets/vpc-troubleshooting.adoc[leveloffset=+2]

[role="_additional-resources"]
[id="additional-resources_rosa-hcp-vpc-aws-egress-lockdown"]
.Additional resources

* link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html[Get Started with Amazon VPC]
* link:https://developer.hashicorp.com/terraform[HashiCorp Terraform documentation]
* link:https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.2/deploy/subnet_discovery/[Subnet Auto Discovery]
* link:https://github.com/openshift-cs/terraform-vpc-example/tree/main/zero-egress[Egress zero Terraform VPC Example]

include::modules/rosa-hcp-creating-account-wide-sts-roles-and-policies.adoc[leveloffset=+1]

include::modules/rosa-sts-byo-oidc.adoc[leveloffset=+1]
include::modules/rosa-operator-config.adoc[leveloffset=+1]

include::modules/rosa-hcp-sts-creating-a-cluster-egress-lockdown-cli.adoc[leveloffset=+1]