oracle-devrel · mlittlec · Jan 20, 2026 · Dec 18, 2025 · Dec 18, 2025 · Dec 18, 2025
diff --git a/labs/docs/README.md b/labs/docs/README.md
@@ -0,0 +1,29 @@
+# Oracle Linux Automation Manager (OLAM) Labs – Ansible Playbook Documentation
+
+## Overview
+
+This directory contains documentation for each playbook and template found in `linux-virt-labs/labs/`. Each file is mapped to a Markdown `.md` file to streamline onboarding, learning, and extension.
+
+Currently, the only included playbook is an introductory "Hello World" example.
+
+---
+
+## Playbooks – Index
+
+| Playbook | Summary | Related Templates/Files |
+| --- | --- | --- |
+| [olam-hello-world.yaml](./olam-hello-world.md) | Minimal demo playbook that prints a welcome message. | (none, standalone) |
+
+---
+
+## Onboarding & Usage
+
+1. **Review olam-hello-world.yaml and its `.md` documentation**
+2. Use as a starting point for new Ansible playbooks or Oracle Linux Automation Manager (OLAM) workflows in this lab directory.
+3. Expand with additional lab playbooks or templates as needed. For each, create a matching Markdown `.md` file in this directory for future developers/operators.
+
+---
+
+## Best Practices
+
+- Each Ansible playbook or Jinja2 template should always have a corresponding `.md` documentation file here.
diff --git a/labs/docs/olam-hello-world.md b/labs/docs/olam-hello-world.md
@@ -0,0 +1,31 @@
+# olam-hello-world.yaml Documentation
+
+## Purpose & Overview
+
+A minimal Ansible playbook demonstrating the structure, syntax, and basic use of Oracle Linux Automation Manager (OLAM). Prints a "Hello World" message for onboarding, classroom, or demonstration environments.
+
+## When to Use
+
+Use this playbook as:
+
+- A starting point for new users learning how Oracle Linux Automation Manager/Ansible works
+- A smoke-test to verify basic Ansible/Oracle Linux Automation Manager installation and task execution
+- A demonstration of Ansible syntax, play/host/task structure
+
+## Key Variables & Inputs
+
+- Runs on: localhost
+- No variables required
+- No input or user interaction expected
+
+## Task Breakdown
+
+- Defines a single play
+- Includes a single task: prints "Hello! Welcome to Oracle Linux Automation Manager." using ansible.builtin.debug
+
+## Dependencies & Relationships
+
+- Standalone, does not require any other roles, modules, or dependencies outside Ansible core.
+- Can be extended with tasks/roles as experience grows.
+
+## Output/Result
diff --git a/ocne/docs/README.md b/ocne/docs/README.md
@@ -0,0 +1,227 @@
+# Deploy Oracle Cloud Native Environment 1
+
+## Overview
+
+This documentation covers all major Ansible playbooks, Jinja2 templates, and supporting assets for the Oracle Cloud Native Environment (Oracle CNE) Lab Suite. It enables users to understand, customize, and extend automated deployments of Oracle Linux, Kubernetes, and Rook/Ceph-powered storage across Oracle Cloud Infrastructure (OCI).
+
+All documentation is auto-generated per playbook or template, providing comprehensive usage, variables, logic, and file relationships.
+
+---
+
+## Contents
+
+- [Deploy Oracle Cloud Native Environment 1](#deploy-oracle-cloud-native-environment-1)
+  - [Overview](#overview)
+  - [Contents](#contents)
+  - [Playbooks](#playbooks)
+  - [Jinja2 Templates](#jinja2-templates)
+  - [Tree Listing](#tree-listing)
+  - [Relationships and Workflow](#relationships-and-workflow)
+  - [Platform Integration](#platform-integration)
+  - [References](#references)
+  - [Quickstart](#quickstart)
+
+---
+
+## Playbooks
+
+| Playbook | Summary | Related Templates / Files |
+| --- | --- | --- |
+| [build.yml](build.md) | Launches OCI VM instances, networks, attaches storage and VNICs. | - |
+| [ceph_deployments.yml](ceph_deployments.md) | Renders and distributes Ceph/Rook/CephFS manifests to control plane nodes. | cluster.j2, filesystem.j2, toolbox.j2, vm.j2, storageclass.j2, pvc.j2 |
+| [create_fss.yml](create_fss.md) | Provisions OCI FSS (NFS), exports, and records IDs for use in storage templates. | fss_vars.j2, fss_pv.j2, fss_pvc.j2, fss_pod.j2 |
+| [create_instance.yml](create_instance.md) | Orchestrates full environment spin-up, network/VLAN, image lookup, instance, storage, and registry creation. | oci_vars.j2, ingress/egress_security_rules.j2, default_vars.yml |
+| [create_lb.yml](create_lb.md) | Provisions OCI LB, configures health checks, backend set, exports LB IP to vars. | lb_vars.j2 |
+| [create_ocir.yml](create_ocir.md) | Provisions OCI Container Registry and writes config for image integration. | ocir_vars.j2 |
+| [create_vlan.yml](create_vlan.md) | Provisions VLAN in OCI/VCN and sets associated security groups. | - |
+| [default_vars.yml](default_vars.md) | Defines default topology, sizing, and feature toggles. | - |
+| [delete_fss.yml](delete_fss.md) / [delete_lb.yml](delete_lb.md) / [delete_ocir.yml](delete_ocir.md) | Teardown/removes FSS, Load Balancer, and Registry resources from OCI. | - |
+| deploy_ocne_* | Orchestrate full Oracle CNE cluster install (compact/full/quick/vlan/none). | myenvironment.j2 (in some flows) |
+| [fss_deployments.yml](fss_deployments.md) | Renders NFS-backed PV, PVC, and test pod manifests from FSS outputs. | fss_pv.j2, fss_pvc.j2, fss_pod.j2 |
+| [host_assign_vlan_ip.yml](host_assign_vlan_ip.md) | Assigns static VLAN IPs and builds SSH trust for all nodes. | - |
+| [host_setup.yml](host_setup.md) | Sets up users, keys, directories, and enables password-less SSH for automation. | - |
+| [ol8_repo_config.yml](ol8_repo_config.md) / [ol9_repo_config.yml](ol9_repo_config.md) | Enables/disables YUM repos for Oracle Linux 8/Oracle Linux 9 and OLCNE install/update. | - |
+| [preconfig_oci_ccm.yml](preconfig_oci_ccm.md) | Sets OCI CCM env variables in .bashrc for controller/cluster manager integration. | - |
+| [provision_istio.yml](provision_istio.md) | Deploys Istio mesh module, renders and applies custom LB setup. | istio_lb.j2 |
+| [provision_kubectl.yml](provision_kubectl.md) | Gives cluster users non-root access to kubectl, copying and exporting config. | - |
+| [provision_oci_ccm.yml](preconfig_oci_ccm.md) | Deploys Oracle CCM for dynamic LB/service and cloud integration. | oci_vars.j2 |
+| [provision_ocne.yml](provision_ocne.md) | Manual path for full cluster install with conditional logic and config export. | myenvironment.j2 |
+
+---
+
+## Jinja2 Templates
+
+| Template | Purpose / Usage |
+| --- | --- |
+| [cluster.j2](./templates/cluster.j2.md) | CephCluster CR (Rook/Ceph storage) |
+| [filesystem.j2](./templates/filesystem.j2.md) | CephFilesystem CR (CephFS persistence) |
+| [toolbox.j2](./templates/toolbox.j2.md) | Rook Ceph toolbox pod/deployment for CLI ops/troubleshooting |
+| [vm.j2](./templates/vm.j2.md) | KubeVirt VM manifest (K8s + OCI image + CephFS + cloud-init) |
+| [storageclass.j2](./templates/storageclass.j2.md) | StorageClass for dynamic CephFS PV provisioning (rook-cephfs) |
+| [pvc.j2](./templates/pvc.j2.md) / [fss_pvc.j2](./templates/fss_pvc.j2.md) | PVCs for CephFS (dynamic/static provisioning flows) |
+| [fss_pv.j2](./templates/fss_pv.j2.md) | Static PersistentVolume for OCI FSS via CSI |
+| [fss_pod.j2](./templates/fss_pod.j2.md) | Test/demo pod mounting the above PVC |
+| [fss_vars.j2](./templates/fss_vars.j2.md) / [oci_vars.j2](./templates/oci_vars.j2.md) / [lb_vars.j2](./templates/lb_vars.j2.md) / [ocir_vars.j2](./templates/ocir_vars.j2.md) | Dynamic YAML config/vars generated by playbooks |
+| [ingress_security_rules.j2](./templates/ingress_security_rules.j2.md) / [egress_security_rules.j2](./templates/egress_security_rules.j2.md) | Vars for security list rules in OCI, rendered by automation |
+| [istio_lb.j2](./templates/istio_lb.j2.md) | OCI LB (internal, flex) setup for Istio Gateway |
+| [myenvironment.j2](./templates/myenvironment.j2.md) | Master configuration file for `olcnectl` environment/module creation |
+
+---
+
+## Tree Listing
+
+```markdown
+|── ocne
+    ├── build.md                          # Launches OCI VM Instances
+    ├── ceph_deployments.md               # Deploys Ceph
+    ├── create_fss.md                     # Provisions OCI FSS (NFS)
+    ├── create_instance.md                # Configures & Deploys Full Instance
+    ├── create_lb.md                      # Provisions OCI Load Balancer
+    ├── create_ocir.md                    # Provisions OCI Container Registry
+    ├── create_vlan.md                    # Provisions OCI/VCN VLAN
+    ├── default_vars.md                   # Defines Deployment Defaults
+    ├── delete_fss.md                     # Removes the OCI FSS 
+    ├── delete_lb.md                      # Removes the OCI Load Balancer
+    ├── delete_ocir.md                    # Removes the OCI Registry
+    ├── deploy_ocne_compact.md            # Performs Oracle CNE Compact Install type
+    ├── deploy_ocne_full.md               # Performs Oracle CNE Full Install type
+    ├── deploy_ocne_none.md               # Configures OCI Instance Ready for manual Oracle CNE Install
+    ├── deploy_ocne_quick.md              # Performs Oracle CNE Quick Install type
+    ├── deploy_ocne_vlan.md               # Provisions OCI/VCN VLAN
+    ├── fss_deployments.md                # Provisions NFS-backed PV and PVC
+    ├── host_assign_vlan_ip.md            # Assigns Static VLAN IPs and Configures SSH Trust Between Nodes 
+    ├── host_setup.md                     # Configures Users, Keys, Directories and Passwordless SSH
+    ├── ol8_repo_config.md                # Enable/Disable YUM Repos to Install Oracle CNE on Oracle Linux 8
+    ├── ol9_repo_config.md                # Enable/Disable YUM Repos to Install Oracle CNE on Oracle Linux 9
+    ├── preconfig_oci_ccm.md              # Configures OCI CCM Environment Variables 
+    ├── provision_istio.md                # Deploys Istio Mesh Module and Configures Custom Load Balancer
+    ├── provision_kubectl.md              # Configure Cluster Users With Non-Root Access to `kubectl` 
+    ├── provision_oci_ccm.md              # Deploys OCI CCM for dynamic Load Balancer
+    ├── provision_ocne.md                 #
+    ├── README.md                         # This file
+    └── templates
+        ├── cluster.j2.md                 # Template for CephCluster
+        ├── egress_security_rules.j2.md   # Template for Egress Security Rules
+        ├── filesystem.j2.md              # Template for CephFilesystem
+        ├── fss_pod.j2.md                 # Template for Test/Demo Pod created in `fss_pvc.j2`
+        ├── fss_pv.j2.md                  # Template for CephFS PV
+        ├── fss_pvc.j2.md                 # Template for CephFS PVC
+        ├── fss_vars.j2.md                # Dynamic Variables Generated by Playbooks
+        ├── ingress_security_rules.j2.md  # Template for Ingress Security Rules
+        ├── istio_lb.j2.md                # Template for OCI Load Balancer setup for Istio Gateway
+        ├── lb_vars.j2.md                 # Dynamic Variables Generated by Playbooks
+        ├── myenvironment.j2.md           # Master Template for Oracle CNE Installation
+        ├── oci_vars.j2.md                # Dynamic Variables Generated by Playbooks
+        ├── ocir_vars.j2.md               # Dynamic Variables Generated by Playbooks
+        ├── pvc.j2.md                     # Template for CephFS PVC
+        ├── storageclass.j2.md            # StorageClass for dynamic CephFS PV provisioning
+        ├── toolbox.j2.md                 # Rook Ceph toolbox pod/deployment for CLI 
+        └── vm.j2.md                      # KubeVirt VM manifest
+```
+
+---
+
+## Relationships and Workflow
+
+- **create_instance.yml** chains the full OCI environment: networks, VMs, FSS, VLAN, LB, registry.
+- Storage and registry IDs/outputs are captured to *_vars.yml and consumed in all downstream playbooks/templates.
+- **ceph_deployments.yml** and **fss_deployments.yml** generate K8s manifests driven by earlier playbook outputs.
+- **deploy_ocne_*** playbooks install the core K8s/OCNE stack, referencing myenvironment.j2 in manual flows.
+- All templates are documented—see individual docs for examples, variable mappings, and rendered outputs.
+- **Teardown** handled by matching delete_*.yml playbooks, using IDs/vars from `*_vars.yml`.
+
+---
+
+## Platform Integration
+
+These playbooks and templates support:
+
+- Oracle Linux 8/9, Kubernetes-on-OCI with full Rook/CephFS storage and KubeVirt support
+- Automated security group/network, VM, and application provisioning
+- Flexible, re-usable yaml/Jinja2 templates for easy environment refresh
+
+## References
+
+- [Oracle Cloud Infrastructure Ansible OCI Collection](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/)  
+- [OCNE Product Docs](https://docs.oracle.com/en/operating-systems/olcne/)  
+- [Rook/CephFS](https://rook.io/docs/rook/latest/ceph-storage/)  
+- [KubeVirt](https://kubevirt.io/)
+
+---
+
+## Quickstart
+
+1. Clone the playbooks repo and review [default_vars.yml](default_vars.yml).
+2. Select a playbook directory under /ocne, review specific .md files for each playbook/template.
+3. Populate or override variable files as required (cloud credentials, subnet, LB, FSS).
+4. Deploy via Ansible: `ansible-playbook create_instance.yml`, `ansible-playbook deploy_ocne_full.yml`, etc.
+5. Explore rendered manifests and configuration in `/docs/ocne`.
+
+**Note:** If running in your own tenancy, read the `linux-virt-labs` GitHub project [README.md](https://github.com/oracle-devrel/linux-virt-labs) and complete the prerequisites before deploying the lab environment.
+
+1. Open a terminal on the Luna Desktop.
+
+1. Clone the `linux-virt-labs` GitHub project.
+
+   ```shell
+   git clone https://github.com/oracle-devrel/linux-virt-labs.git
+   ```
+
+1. Change into the working directory.
+
+   ```shell
+   cd linux-virt-labs/ocne2
+   ```
+
+1. Install the required collections.
+
+   ```shell
+   ansible-galaxy collection install -r requirements.yml
+   ```
+
+1. **Customize variables**
+
+   Edit `default_vars.yml` to set your:
+   - Compartment, region, and other tenancy details
+   - Instance/layout configuration
+   - Feature flags (block storage, FSS, Podman, Oracle CNE variant, etc.)
+
+1. Deploy the lab environment.
+
+   Use the `create_instance.yml` file to initiate the creation of a preconfigured environment which you can use to run Oracle CNE. The examples below, while not exhaustive, demonstrate how to deploy different environments using the Oracle CNE repository.
+
+   a. Deploy a single Oracle Linux Environment ready for you to setup and install an Oracle CNE install using the compact deployment method. The three Oracle Linux instances will be configured with:
+
+      - An Oracle user account (used during the installation) with sudo access
+      - Key-based SSH, also known as password-less SSH, between the hosts
+      - Installation od Oracle CNE
+
+         i. Update the Oracle CNE configuration.
+
+           ```shell
+           cat << EOF | tee instances.yml > /dev/null
+           compute_instances:
+            1:
+              instance_name: "ocne-compact"
+              type: "operator"
+           EOF
+           ```
+
+        ii. Deploy the environment.
+
+          ```shell
+          ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e ocne_type=compact -e "@instances.yml"
+          ```
+
+   b. Deploy a 3-Node Oracle Linux Environment ready for you to setup and install an Oracle CNE install using the Quick Install method. Each of the three Oracle Linux instances will be configured with:
+
+      - An Oracle user account (used during the installation) with sudo access
+      - Key-based SSH, also known as password-less SSH, between the hosts
+
+      ```shell
+      ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e ocne_type=none
+      ```
+
+---
+
+*For detailed explanations of any playbook, template, or output file, see the corresponding `.md` file in this directory.*
diff --git a/ocne/docs/build.md b/ocne/docs/build.md
@@ -0,0 +1,61 @@
+# build.yml Documentation
+
+## Purpose & Overview
+
+Launches a new Oracle Cloud Infrastructure (OCI) compute instance, configures its network interfaces, optionally attaches storage, and registers the instance for subsequent Ansible automation workflows. Includes support for both direct subnet and VLAN setups, and can provision additional block volume storage for worker nodes.
+
+## When to Use
+
+Use this playbook when:
+
+- You need to automate the provisioning of compute instances on OCI as part of a Kubernetes or Oracle Linux infrastructure deployment.
+- You want to ensure every new VM is created, networked, optionally VLAN-attached, and storage-augmented in a repeatable, debug-friendly way.
+
+## Key Variables & Inputs
+
+- `my_availability_domain`: OCI AD for the instance.
+- `my_compartment_id`: OCI compartment OCID.
+- `my_subnet_id`: Target subnet OCID for primary VNIC.
+- `ol_image_id`: Image OCID for the new instance.
+- `instance_shape`: OCI shape (resource allocation profile).
+- `instance_ocpus`, `instance_memory`: vCPU and RAM config.
+- `private_key`: SSH private key name (for generating authorized_keys).
+- `item.value.instance_name`: Optional, controls hostname.
+- `use_vlan`, `my_vlan_id`: If attaching VLAN VNICs.
+- `add_ceph_block_storage`, `ceph_volume_size_in_gbs`: If adding Ceph block storage to worker nodes.
+- `debug_enabled`: Toggle debug/info output.
+- Additional vars: see playbook for all details; many are templated per host/item.
+
+## Task Breakdown
+
+- **Launch Instance:** Uses `oracle.oci.oci_compute_instance` to provision a new compute VM with defined resources, SSH keys, monitoring/management config.
+- **Show Details:** Prints result if `debug_enabled`.
+- **Set Facts:** Saves instance OCID, display name for downstream tasks.
+- **Get VNIC Info:** Fetches and assigns both private and public IPs, introspects OCI VNIC attachments.
+- **VLAN Support:** Optional creation/attachment of VLAN VNICs if `use_vlan`.
+- **Ceph Block Volumes:** Optionally attaches OCI block storage for Ceph to worker instances if enabled.
+- **Output:** Prints important IPs and identifiers for workflow use, if `debug_enabled`.
+- **Register Host:** Adds VM details to Ansible's runtime host inventory for further playbook tasks.
+
+## Dependencies & Relationships
+
+- Requires Oracle OCI Ansible Collection, incl. `oci_compute_instance`, `oci_blockstorage_volume`, `oci_compute_volume_attachment`.
+- Consumes variables provided at group/host level or passed via extra-vars.
+- Optionally invokes Jinja2 templates as referenced by related post-creation provisioning playbooks (not directly in this file).
+
+## Output/Result
+
+- A new compute instance, optionally VLAN-attached and/or equipped with Ceph storage.
+- Adds instance to Ansible host file and sets necessary variables for future steps.
+
+## Example Run
+
+```bash
+ansible-playbook build.yml \
+  -e "my_availability_domain=..." \
+  -e "my_compartment_id=..." \
+  -e "my_subnet_id=..." \
+  -e "ol_image_id=..." \
+  -e "instance_shape=VM.Standard.E4.Flex" \
+  -e "instance_ocpus=2" \
+  -e "instance_memory=16"