docs: add readmes

ludwig-mueller · ludwig-mueller · commit 9a0dd03c975f · 2025-09-19T16:07:16.000+02:00
diff --git a/reference-architectures/standard-openshift/deploy-arch-ibm-pvs-inf-standard-openshift.md b/reference-architectures/standard-openshift/deploy-arch-ibm-pvs-inf-standard-openshift.md
@@ -31,7 +31,7 @@ compliance:
 
 The Quickstart OpenShift deployment on Power Virtual Server with a VPC landing zone uses the Red Hat IPI installer to set up an OpenShift cluster. Before the deployment begins, it provisions VPC services and creates a Power Virtual Server workspace, which together form the landing zone used to access and manage the cluster.
 
-The number of PowerVS master and worker nodes and their respective compute configurations can be freely configured during deployment. Optionally, Monitoring and Security and Compliance Center Workload Protection can also be configured.
+The number of PowerVS master and worker nodes and their respective compute configurations can be configured during deployment. Optionally, Monitoring and Security and Compliance Center Workload Protection can also be configured.
 
 ## Architecture diagram
 {: #standard-openshift-architecture-diagram}
@@ -45,8 +45,8 @@ The number of PowerVS master and worker nodes and their respective compute confi
 
 IBM Cloud® Power Virtual Servers (PowerVS) is a public cloud offering that an enterprise can use to establish its own private IBM Power computing environment on shared public cloud infrastructure. PowerVS is logically isolated from all other public cloud tenants and infrastructure components, creating a private, secure place on the public cloud. This deployable architecture provides a framework to build a PowerVS offering according to the best practices and requirements from the IBM Cloud.
 
-## Components
-{: #standard-openshift-components}
+## Landing Zone Components
+{: #standard-openshift-landing-zone-components}
 
 ### VPC architecture decisions
 {: #standard-openshift-vpc-components-arch}
@@ -59,6 +59,7 @@ IBM Cloud® Power Virtual Servers (PowerVS) is a public cloud offering that an e
 |* Allow customer to choose operating system from two most widely used commercial Linux operating system offerings  \n * Support new OS releases|Linux operating system|Red Hat Enterprise Linux (RHEL)| |
 |* Create a virtual server instance as the only management access point to the landscape|Bastion host VPC instance|Create a Linux VPC instance that acts as a bastion host. Configure ACL and security group rules to allow SSH connectivity (port 22). Add a public IP address to the VPC instance. Allow connectivity from a restricted and limited number of public IP addresses. Allow connectivity from IP addresses of the Schematics engine nodes| |
 |* Create a virtual server instance that can act as an internet proxy server |Network services VPC instance|Create a Linux VPC instance that can host management components. Preconfigure ACL and security group rules to allow traffic over private networks only.|Configure application load balancer to act as proxy server manually, Modify number of virtual server instances and allowed ports in preset or perform the modifications manually|
+|* Create DNS Service instance as pre-requisite for IPI installer | DNS Service Instance | Create a DNS Service instance and a custom resolver to internally resolve the cluster domain. | |
 |* Ensure financial services compliancy for VPC services  \n * Perform network setup of all created services  \n * Perform network isolation of all created services  \n * Ensure all created services are interconnected |Secure landing zone components|Create a minimum set of required components for a secure landing zone|Create a modified set of required components for a secure landing zone in preset|
 |* Allow customer to optionally enable monitoring in the deployment|IBM Cloud® monitoring instance and Monitoring Host VPC Instance|Optionally, create or import an existing IBM Cloud® monitoring instance (customer provided details) and create and pre-configure the Monitoring Host VPC instance to  collect information and send it to the IBM Cloud® monitoring instance.| |
 |* Allow customer to optionally enable [Security and Compliance Center Workload Protection](/docs/workload-protection) in the deployment \n * Collect posture management information, enable vulnerability scanning and threat detection|IBM Cloud® Security and Compliance Center Workload Protection and SCC Workload Protection agent on all VPC instances in the deployment.|Optionally, create an IBM Cloud® Security and Compliance Center Workload Protection instance and install and setup the SCC Workload Protection agent on all VPC instances in the deployment (bastion, network services, monitoring hosts).| |
@@ -73,17 +74,6 @@ IBM Cloud® Power Virtual Servers (PowerVS) is a public cloud offering that an e
 |* Preload a public SSH key that is injected into every OS deployment|Preloaded SSH public key|Preload customer specified SSH public key| |
 {: caption="Table 2. PowerVS workspace architecture decisions" caption-side="bottom"}
 
-### PowerVS management services architecture decisions
-{: #standard-openshift-pvs-components-mgmt}
-
-| Requirement | Component | Choice | Alternative choice |
-|-------------|-----------|--------------------|--------------------|
-|* Ensure public internet connectivity from all the instances to be deployed in PowerVS workspace|SQUID proxy|Set up SQUID proxy software on Linux virtual server instance that is running in edge VPC|  |
-|* Provide shared NFS storage that might be directly attached to all the instances to be deployed in PowerVS workspace| File storage shares in VPC|Use the files storage share service running in VPC. Disk size is specified by the user.| |
-|* Provide time synchronization to all instances to be deployed in PowerVS workspace|NTP forwarder|Synchronize time by using public NTP servers. Set up time synchronization on Linux virtual server instance that is running in workload VPC.|By using time synchronization servers directly reachable from PowerVS workspace, NTP forwarder is not required.|
-|* Provide a DNS forwarder to a DNS server not directly reachable from PowerVS workspace (for example, running on-premises or in other isolated environment)|DNS forwarder|Configure DNS forwarder on Linux virtual server instance that is running in edge VPC| By using default IBM Cloud DNS service, DNS forwarder is not needed. Direct domain name resolution is possible.|
-{: caption="Table 3. PowerVS management services architecture decisions" caption-side="bottom"}
-
 ### Network security architecture decisions
 {: #standard-openshift-net-sec}
 
@@ -92,17 +82,8 @@ IBM Cloud® Power Virtual Servers (PowerVS) is a public cloud offering that an e
 |* Preload VPN configuration to simplify VPN setup|VPNs|VPN configuration is the responsibility of the customer. Automation creates a client to site VPN server| |
 |* Enable floating IP on bastion host to execute deployment|Floating IPs on bastion host in management VPC|Use floating IP on bastion host from IBM Schematics to complete deployment| |
 |* Isolate management VSI and allow only a limited number of network connections  \n * All other connections from or to management VPC are forbidden|Security group rules for management VSI|Open following ports by default: 22 (for limited number of IPs).  \n All ports to PowerVS workspace are open.  \n All ports to other VPCs are open.|More ports might be opened in preset or added manually after deployment|
-|* Isolate network services VSI, VPEs and NFSaaS |Security group rules in edge VPC|Separate security groups are created for each component and only certain IPs or Ports are allowed. |More ports might be opened in preset or added manually after deployment|
-{: caption="Table 4. Network security architecture decisions" caption-side="bottom"}
-
-### PowerVS instance - architecture decisions
-{: #standard-openshift-pvs-components}
-
-| Requirement | Component | Choice | Alternative choice |
-|-------------|-----------|--------------------|--------------------|
-|* Deploy PowerVS instance for POC or demo purposes  \n * Use pre-defined t-shirt sizes with regards to memory, cpu, OS and storage | PowerVS instance | * Attach all required storage filesystems  \n * Attach networks for management and backup  \n * Connect instance with infrastructure management services like DNS, NTP, NFS  | * Allow customer to specify memory, cpu, OS, storage and additional parameters \n * OS configuration is the responsibility of the customer |
-{: caption="Table 5. PowerVS workspace architecture decisions" caption-side="bottom"}
-
+|* Isolate network services VSI and VPEs |Security group rules in edge VPC|Separate security groups are created for each component and only certain IPs or Ports are allowed. |More ports might be opened in preset or added manually after deployment|
+{: caption="Table 3. Network security architecture decisions" caption-side="bottom"}
 
 ### Key and password management architecture decisions
 {: #standard-openshift-key-pw}
@@ -112,3 +93,17 @@ IBM Cloud® Power Virtual Servers (PowerVS) is a public cloud offering that an e
 |* Use public/private SSH key to access virtual server instances by using SSH  \n * Use SSH proxy to log in to all virtual server instances by using the bastion host  \n * Do not store private ssh key on any virtual instances, also not on the bastion host  \n * Do not allow any other SSH login methods except the one with specified private/public SSH key pair|Public SSH key - provided by customer. Private SSH key - provided by customer.|Ask customer to specify the keys. Accept the input as secure parameter or as reference to the key stored in IBM Cloud Secure Storage Manager. Do not print SSH keys in any log files. Do not persist private SSH key.|                    |
 |* Use public/private SSH key to access virtual server instances by using SSH  \n * Use SSH proxy to log in to all virtual server instances by using the private IPS of instances using a VPN client  \n * Do not store private ssh key on any virtual instances  \n * Do not allow any other SSH login methods except the one with specified private/public SSH key pair|Public SSH key - provided by customer. Private SSH key - provided by customer.|Ask customer to specify the keys. Accept the input as secure parameter or as reference to the key stored in IBM Cloud Secure Storage Manager. Do not print SSH keys in any log files. Do not persist private SSH key.|                    |
 {: caption="Table 5. Key and passwords management architecture decisions" caption-side="bottom"}
+
+## OpenShift Components
+{: #standard-openshift-openshift-components}
+
+Once the landing zone components are deployed, this architecture leverages the [RedHat IPI installer](https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/installing_on_ibm_power_virtual_server/index){: external} to create an OpenShift cluster.
+
+| Requirement | Component | Choice | Alternative choice |
+|-------------|-----------|--------|--------------------|
+|* Deploy PowerVS instances for Bootstrap (temporary), Master, and Worker nodes. | PowerVS instances | The customer can specify the number of master and worker nodes and customize their compute profiles. |
+|* Modify the DNS Service instance to correctly resolve the cluster API | DNS Service instance | Add CNAME entries to DNS zone to resolve internal and external cluster APIs. |
+|* Application Load Balancers to establish connectivity to the cluster API. | Three Application Load Balancers | One for internal API, one for external api, and one for the applications deployed in the cluster. |
+|* Use DHCP to dynamically assign IP addresses to the nodes | DHCP Subnet in PowerVS | Machine network dynamically assigns IP addresses to the nodes. |
+|* Modify security groups to allow network traffic to API. | Default Security Group | The default security group is attached to the load balancers and configured so the required network traffic is able to pass. |
+{: caption="Table 6. OpenShift architecture decisions" caption-side="bottom"}
diff --git a/solutions/standard-openshift/README.md b/solutions/standard-openshift/README.md
@@ -1,3 +1,45 @@
+# IBM Cloud Solution for Power Virtual Server with VPC Landing Zone Quickstart Openshift Variation
+
+This example sets up an OpenShift Cluster on PowerVS following infrastructure:
+- A **VPC Infrastructure** with the following components:
+    - One VSI for management (jump/bastion)
+    - One VSI for network-services configured as squid proxy (using Ansible Galaxy collection roles [ibm.power_linux_sap collection](https://galaxy.ansible.com/ui/repo/published/ibm/power_linux_sap/). This VSI also acts as central ansible execution node.
+    - Optional VSI for Monitoring host
+    - Optional [Client to site VPN server](https://cloud.ibm.com/docs/vpc?topic=vpc-vpn-client-to-site-overview)
+    - Optional [IBM Cloud Security and Compliance Center Workload Protection](https://cloud.ibm.com/docs/workload-protection) and SCC Workload Protection agent configuration on the VSIs in the deployment
+    - IBM Cloud Object storage(COS) Virtual Private endpoint gateway(VPE)
+    - IBM Cloud Object storage(COS) Instance and buckets
+    - VPC flow logs
+    - KMS keys
+    - Activity tracker
+    - Optional Secrets Manager Instance Instance with private certificate.
+
+- A local **transit gateway**
+- An IBM Cloud DNS Service Instance
+- An optional IBM Cloud Monitoring Instance
+
+- A **Power Virtual Server** workspace with the following features:
+    - A DHCP machine subnet to which all nodes are assigned.
+    - Attaches the PowerVS workspace to transit gateway.
+    - Creates an SSH key.
+
+- A configurable number of **PowerVS Instances**:
+    - 1 or 3 master nodes
+    - 2 or more worker nodes
+    - Custom profile (cores, memory, machine type, core type)
+
+## Solutions
+
+| Variation  | Available on IBM Catalog  |  Requires Schematics Workspace ID | Creates VPC Landing Zone | Performs VPC VSI OS Config | Creates PowerVS Infrastructure | Creates PowerVS Instance | Creates OpenShift Cluster on PowerVS |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
+| [Quickstart Openshift](./)    | :heavy_check_mark:  |   N/A  | :heavy_check_mark:| :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark: | :heavy_check_mark: |
+
+## Reference architecture
+[Quickstart Openshift](https://github.com/terraform-ibm-modules/terraform-ibm-powervs-infrastructure/blob/main/reference-architectures/standard-openshift/deploy-arch-ibm-pvs-inf-standard-openshift.md)
+
+## Architecture diagram
+![Quickstart Openshift](https://github.com/terraform-ibm-modules/terraform-ibm-powervs-infrastructure/blob/main/reference-architectures/standard-openshift/deploy-arch-ibm-pvs-inf-standard-openshift.svg)
+
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ### Requirements
 
