From 974993b22d392c9b08f96938c44293c20845d82e Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Thu, 18 Dec 2025 14:42:09 +0000 Subject: [PATCH 01/10] Add new README.md file to the ocne2 directory --- ocne2/docs/README.md | 193 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 ocne2/docs/README.md diff --git a/ocne2/docs/README.md b/ocne2/docs/README.md new file mode 100644 index 0000000..134d8bf --- /dev/null +++ b/ocne2/docs/README.md @@ -0,0 +1,193 @@ +# Deploy Oracle Cloud Native Environment + +## Introduction + +Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for developing and managing cloud-native applications. The Kubernetes module is the core module. It deploys and manages containers and automatically installs and configures CRI-O, runC, and Kata Containers. CRI-O manages the container runtime for a Kubernetes cluster, which may be either runC or Kata Containers. + +## Deploy Oracle CNE + +**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 2 repository. + + a. Deploy a single Oracle Linux instance configured with the following: + + - An Oracle user account (used during the installation) with sudo access + - Key-based SSH, also known as password-less SSH, between the hosts + - A working KVM libvirt environment + + ```shell + ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e ocne_type=libvirt + ``` + + This deploys a new Oracle Linux instance with a working libvirt environment ready for you to setup and install an Oracle CNE 2 install of your choice. + + b. Deploy a single Oracle Linux instance configured with the following: + + - Install of Oracle Cloud Native Environment (Oracle CNE) + - A single control node and one worker node + - A working KVM libvirt environment + + ```shell + ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e install_ocne_rpm=true -e create_ocne_cluster=true -e "ocne_cluster_node_options='-n 1 -w 1'" + ``` + + If you want to use this for development together with Podman on the same instance add the `-e use_podman=true` parameter to the command as shown below: + + ```shell + ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e use_podman=true -e install_ocne_rpm=true -e create_ocne_cluster=true -e "ocne_cluster_node_options='-n 1 -w 1'" + ``` + + c. The default values (see `defaults.yml`) can be overridden by creating a separate file with the revised definition to be created. This example deploys an Oracle Linux 9 (`os_version: 9`) instance with 8 CPUs (`instance_ocpus: 8`) and 128Mb memory (`instance_memory: 128`) as well as increasing the boot volume size to be 256 Gb (`boot_volume_size_in_gbs: 256`). + + d. Increase the Boot volume size, install libvirt, and use Oracle Linux 9. + + ```shell + cat << EOF | tee instances.yml > /dev/null + compute_instances: + 1: + instance_name: "ocne" + type: "server" + instance_ocpus: 8 + instance_memory: 128 + boot_volume_size_in_gbs: 256 + ocne_type: "libvirt" + install_ocne_rpm: true + update_all: true + os_version: "9" + EOF + ``` + + e. Deploy a single Oracle Linux 9 instance configured using the custom configuration created in `instances.yml`: + + ```shell + ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" + ``` + + **Note:** The free lab environment requires the extra variable `localhost_python_interpreter`, which sets `ansible_python_interpreter` for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules. Either remove, or update this variable to match your system's requirements. + + The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command. + + > **Important:** Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab. + +--- + +## Documentation Table + +| File Name | Description | +| - | - | +| [block.md](./block.md) | Add block storage (volumes) to OCI compute instances | +| [build.md](./build.md) | Launch and configure compute instances in OCI | +| [create_fss.md](./create_fss.md) | Provision OCI File Storage Service (FSS) components | +| [create_instance.md](./create_instance.md) | **Main Orchestration:** Provisions all resources and runs end-to-end lab automation | +| [default_vars.md](./default_vars.md) | Defines structure, sizing, cluster, user, and feature toggle variables used by all playbooks. | +| [delete_fss.md](./delete_fss.md) | Teardown (delete) FSS components cleanly | +| [deploy_ocne_libvirt.md](./deploy_ocne_libvirt.md) | Deploy OCNE cluster on local KVM/Libvirt | +| [deploy_ocne_oci.md](./depploy_ocne_oci.md) | Deploy OCNE cluster directly on OCI infrastructure | +| [deploy_ocne_none.md](./deploy_ocne_none.md) | No-operation placeholder for skipping cluster setup | +| [fss_deployments.md](./fss_deployments.md) | Generates Kubernetes manifests for FSS-backed PersistentVolume/Pod | +| [host_setup.md](./host_setup.md) | Prepares OS/user/SSH/facts on each instance | +| [provision_podman.md](./provision_podmam.md) | Install Podman and container tools for OCI/Linux | +| [requirements.md](./requirements.md) | Ansible Galaxy collections needed for all playbooks | +| [update_all_rpms.md](./update_all_rpms.md) | Update all OS packages and reboot as needed | +| [templates/egress_security_rules.j2.md](./templates/egress_security_reules.j2.md) | Jinja2 template for outbound network security rules (exported as YAML var file) | +| [templates/ingress_security_rules.j2.md](./templates/ingress_security_rules.j2.md) | Jinja2 template for inbound network security rules (exported as YAML var file) | +| [templates/fss_pv.j2.md](./templates/fss_pv.j2.md) | Template for Kubernetes PersistentVolume integrating OCI FSS. | +| [templates/fss_pvc.j2.md](./templates/fss_pvc.j2.md) | Template for Kubernetes PersistentVolumeClaim (PVC) for FSS | +| [templates/fss_pod.j2.md](./templates/fss_pod.j2.md) | Template for sample/test K8s Pod using the FSS PVC | +| [templates/fss_vars.j2.md](./templates/fss_vars.j2.md) | Template for storing FSS variable output during provisioning | +| [templates/oci_vars.j2.md](./templates/oci_vars.j2.md) | Template for storing key OCI variables as a YAML snippet | + +## Tree Listing + +```markdown +├── ocne2 +│   ├── block.md +│   ├── build.md +│   ├── create_fss.md +│   ├── create_instance.md +│   ├── default_vars.md +│   ├── delete_fss.md +│   ├── deploy_ocne_libvirt.md +│   ├── deploy_ocne_none.md +│   ├── deploy_ocne_oci.md +│   ├── fss_deployments.md +│   ├── host_setup.md +│   ├── provision_podman.md +│   ├── README-Revised.md +│   ├── requirements.md +│   ├── templates +│   │   ├── egress_security_rules.j2.md +│   │   ├── fss_pod.j2.md +│   │   ├── fss_pv.j2.md +│   │   ├── fss_pvc.j2.md +│   │   ├── fss_vars.j2.md +│   │   ├── ingress_security_rules.j2.md +│   │   └── oci_vars.j2.md +│   └── update_all_rpms.md +└── README.md +``` + +--- + +## Relationships and Data Flow + +- **create_instance.yml** triggers almost all other playbooks and templates. +- **build.yml** → **block.yml** (for volume attachment) +- **create_fss.yml** → **fss_vars.j2** (creates variables for storage/manifest templates) +- **fss_deployments.yml** utilizes **fss_pv.j2**, **fss_pvc.j2**, **fss_pod.j2** +- **deploy_*.yml** (libvirt/oci/none) drive lab or cluster setup per deployment type. +- **host_setup.yml** is invoked for each instance as part of setup. +- Security rules are templated by **ingress_security_rules.j2** and **egress_security_rules.j2**, consumed whenever a new subnet or security list is created. + +--- + +## Tips and Best Practices + +- Review each individual Markdown doc for file-specific details, usage notes, and in-context examples. +- Always use version-pinned dependency management via `requirements.yml`. +- Keep code and docs in sync: update the corresponding `.md` file for any playbook, role, or template change. + +--- + +## References + +- [Oracle Cloud Infrastructure Documentation](https://docs.oracle.com/en-us/iaas/Content/home.htm) +- [OCI Ansible Collection](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/) +- [Oracle Cloud Native Environment](https://docs.oracle.com/en/solutions/deploy-cloud-native-environments/index.html) +- [Kubernetes Docs](https://kubernetes.io/docs/) +- [Podman Docs](https://podman.io/) + +--- + +For troubleshooting, edge use cases, or advanced onboarding, see individual `.md` files in this directory. + From 582dd65b2805f3663cf9a8b9a7e50e75a2f1b780 Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Thu, 18 Dec 2025 14:45:15 +0000 Subject: [PATCH 02/10] Add new block.md & build.md files to the ocne2 directory --- ocne2/docs/block.md | 72 ++++++++++++++++++++++++++++++++++++++++++++ ocne2/docs/build.md | 73 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 ocne2/docs/block.md create mode 100644 ocne2/docs/build.md diff --git a/ocne2/docs/block.md b/ocne2/docs/block.md new file mode 100644 index 0000000..26eb85a --- /dev/null +++ b/ocne2/docs/block.md @@ -0,0 +1,72 @@ +# block.yml — Add Block Volumes to OCI Instance + +This playbook block is included by other playbooks (commonly `build.yml`) to provision and attach block storage volumes to an Oracle Cloud Infrastructure (OCI) compute instance. + +## Purpose + +- Automates the creation, registration, and attachment of additional block storage volumes to an OCI instance. +- Used to enable extra data storage or application volumes. + +## Requirements + +- The Oracle OCI Ansible Collection (`oracle.oci`). +- Variables provided by calling playbook: + - `my_compartment_id` + - `my_availability_domain` + - `instance_id` + - `block_volume_size_in_gbs` + - `block_devices` +- The source playbook should set `add_block_storage: true` to enable execution. + +## Key Variables + +| Variable | Description | +|----------------------------|-------------------------------------------| +| `my_compartment_id` | OCID of the compartment | +| `my_availability_domain` | Availability domain for allocation | +| `instance_id` | OCID of the target compute instance | +| `block_volume_size_in_gbs` | Size (GB) of each block volume | +| `block_devices` | List of device labels (default: b-f) | + +## Main Tasks + +1. **Create block volume:** + Provisions a new OCI block volume resource in the specified AD/compartment. + +2. **Set volume ID:** + Registers the new volume’s OCID for later attachment. + +3. **Attach volume:** + Attaches the volume to the instance using OCI’s `paravirtualized` type. + +- Built-in retry/delay logic for reliable provisioning. + +## Relationships + +- **Included by:** `build.yml` +- **Needs variables set by:** `create_instance.yml`, `default_vars.yml` +- **Part of main stack:** Used only if `add_block_storage` is set. + +## References + +- [OCI Block Volume Docs](https://docs.oracle.com/en-us/iaas/Content/Block/Concepts/overview.htm) +- [oracle.oci.oci_blockstorage_volume](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_blockstorage_volume_module.html) +- [oracle.oci.oci_compute_volume_attachment](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_compute_volume_attachment_module.html) + +## Example Usage + +Typically not called directly. Included by looping in `build.yml` to add `block_count` number of volumes: + +```yaml +- name: Add block storage to an instance + include_tasks: "block.yml" + loop: "{{ query('sequence', 'start=1 end=' + (block_count) | string) }}" + vars: + block_devices: + - b + - c + - d + - e + - f +``` + diff --git a/ocne2/docs/build.md b/ocne2/docs/build.md new file mode 100644 index 0000000..6d43033 --- /dev/null +++ b/ocne2/docs/build.md @@ -0,0 +1,73 @@ +# build.yml — Launch and Configure OCI Compute Instance + +This playbook provisions an Oracle Cloud Infrastructure (OCI) compute instance, configures its networking, attaches block storage volumes (by including `block.yml`), and sets up in-memory inventory for subsequent playbooks. + +## Purpose + +- Launches a compute instance on OCI using provided parameters and variables +- Attaches one or more block storage volumes for additional data/application storage +- Collects and stores instance metadata (OCIDs, IP addresses) for orchestration +- Prepares new host for further configuration and Ansible-driven automation + +## Requirements + +- Oracle OCI Ansible Collection (`oracle.oci`) +- Variables provided as part of Ansible inventory or the parent playbook: + - `my_compartment_id` + - `my_availability_domain` + - `ol_image_id` + - `instance_shape` + - `my_subnet_id` + - `block_count` and `block_volume_size_in_gbs` + - SSH public key in `/.ssh/.pub` +- Optional: + - `debug_enabled` toggles extra log/debug output + - Additional host and instance group variables + +## Key Variables + +| Variable | Description | +|----------------------------|-------------------------------------------------------| +| `my_compartment_id` | OCID of target compartment | +| `my_availability_domain` | Availability domain | +| `ol_image_id` | OCID of Oracle Linux image for boot volume | +| `instance_shape` | OCI compute shape | +| `block_count` | Number of block volumes to attach | +| `block_volume_size_in_gbs` | Size per block storage volume | +| `private_key` | SSH private key name for host access | +| `item.value.*` | Per-instance override variables (see parent playbook) | + +## Main Tasks + +1. **Launch instance:** + Provisions a new VM on OCI per specified variables (network, OS, resources). + +2. **Set and print facts:** + Registers OCIDs, private/public IPs, and details for in-memory and downstream use. + +3. **Attach block storage:** + Includes `block.yml` per `block_count` for extra volume provisioning. + +4. **Configure Ansible inventory:** + Dynamically adds launched instance to in-memory `add_host` inventory group for later playbook/role execution. + +## Relationships + +- **Invokes:** `block.yml` to add block storage +- **Registered variables used by:** `create_instance.yml` and sub-sequent configuration +- **Dependent on:** Variables from `default_vars.yml`, parent calls in `create_instance.yml` + +## References + +- [oracle.oci.oci_compute_instance](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_compute_instance_module.html) +- [add_host module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/add_host_module.html) + +## Example Usage + +Called/looped within `create_instance.yml` for each defined instance: + +```yaml +- name: Build an instance + include_tasks: "build.yml" + loop: "{{ lookup('dict', compute_instances, wantlist=True) }}" + From c8e0626ee813897225eff4c20bc930dff5dfbe67 Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Thu, 18 Dec 2025 14:49:35 +0000 Subject: [PATCH 03/10] Update the README.md file in the ocne2 directory --- ocne2/docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ocne2/docs/README.md b/ocne2/docs/README.md index 134d8bf..963ca1a 100644 --- a/ocne2/docs/README.md +++ b/ocne2/docs/README.md @@ -4,7 +4,7 @@ Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for developing and managing cloud-native applications. The Kubernetes module is the core module. It deploys and manages containers and automatically installs and configures CRI-O, runC, and Kata Containers. CRI-O manages the container runtime for a Kubernetes cluster, which may be either runC or Kata Containers. -## Deploy Oracle CNE +## Deploy Oracle CNE Using These Ansible Playbooks **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. From 4dcd1ac5690fde0dff203801984d6551d87cacf2 Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Thu, 18 Dec 2025 15:09:31 +0000 Subject: [PATCH 04/10] Add the rest of the main Playbooks for deploying OCNE 2 --- ocne2/docs/create_fss.md | 66 ++++++++++++++++++++++++ ocne2/docs/create_instance.md | 83 +++++++++++++++++++++++++++++++ ocne2/docs/default_vars.md | 69 +++++++++++++++++++++++++ ocne2/docs/delete_fss.md | 43 ++++++++++++++++ ocne2/docs/deploy_ocne_libvirt.md | 54 ++++++++++++++++++++ ocne2/docs/deploy_ocne_none.md | 33 ++++++++++++ ocne2/docs/deploy_ocne_oci.md | 64 ++++++++++++++++++++++++ ocne2/docs/fss_deployments.md | 48 ++++++++++++++++++ ocne2/docs/host_setup.md | 56 +++++++++++++++++++++ ocne2/docs/provision_podman.md | 42 ++++++++++++++++ ocne2/docs/requirements.md | 39 +++++++++++++++ ocne2/docs/update_all_rpms.md | 39 +++++++++++++++ 12 files changed, 636 insertions(+) create mode 100644 ocne2/docs/create_fss.md create mode 100644 ocne2/docs/create_instance.md create mode 100644 ocne2/docs/default_vars.md create mode 100644 ocne2/docs/delete_fss.md create mode 100644 ocne2/docs/deploy_ocne_libvirt.md create mode 100644 ocne2/docs/deploy_ocne_none.md create mode 100644 ocne2/docs/deploy_ocne_oci.md create mode 100644 ocne2/docs/fss_deployments.md create mode 100644 ocne2/docs/host_setup.md create mode 100644 ocne2/docs/provision_podman.md create mode 100644 ocne2/docs/requirements.md create mode 100644 ocne2/docs/update_all_rpms.md diff --git a/ocne2/docs/create_fss.md b/ocne2/docs/create_fss.md new file mode 100644 index 0000000..c38e6a4 --- /dev/null +++ b/ocne2/docs/create_fss.md @@ -0,0 +1,66 @@ +# create_fss.yml — Provision Oracle Cloud File Storage Service (FSS) + +This playbook provisions OCI File Storage (FSS) for use as network-attached storage for compute instances and Kubernetes clusters. + +## Purpose + +- Automates creation and configuration of an FSS file system, mount target, and export. +- Gathers all identifiers (OCIDs, private IPs) for use in subsequent infrastructure and application stacks. +- Renders variables file (`fss_vars.yml`) for downstream consumption (e.g., Kubernetes volumes). + +## Requirements + +- Oracle OCI Ansible Collection (`oracle.oci`). +- Variables from calling playbook: + - `my_availability_domain` + - `my_compartment_id` + - `my_subnet_id` +- Optional: `debug_enabled` for additional output. + +## Key Variables + +| Variable | Description | +|---------------------------|------------------------------------------------------| +| `my_availability_domain` | Target AD for storage | +| `my_compartment_id` | Compartment for all objects | +| `my_subnet_id` | Subnet for mounting FSS | +| `mount_target_id` | ID of the mount target (auto-set) | +| `mount_target_ip_address` | Private IP for mount operations (auto-set) | +| `file_system_id` | OCID for the file system (auto-set) | +| `export_id` | OCID for the FSS export (auto-set) | +| `export_path` | Path for the NFS export (auto-set) | + +## Main Tasks + +1. **Provision mount target:** + Creates an OCI mount target in a subnet for access. + +2. **Provision file system:** + Allocates the FSS file system in the same AD/compartment. + +3. **Export configuration:** + Sets export rules for global read-write NFS access. + +4. **Outputs variables:** + Generates `fss_vars.yml` for use in Kubernetes or downstream Ansible tasks. + +## Relationships + +- **Referenced by:** `create_instance.yml` (teardown in `delete_fss.yml`) +- **Produces variables for:** Jinja2 templates (`fss_pv.j2`, `fss_pvc.j2`, `fss_pod.j2`) +- **Main consumer:** Kubernetes storage provisioning via `fss_deployments.yml` + +## References + +- [OCI File Storage Service](https://docs.oracle.com/en-us/iaas/Content/File/Concepts/filestorageoverview.htm) +- [oracle.oci.oci_file_storage_mount_target](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_file_storage_mount_target_module.html) +- [oracle.oci.oci_file_storage_file_system](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_file_storage_file_system_module.html) +- [oracle.oci.oci_file_storage_export](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_file_storage_export_module.html) + +## Example Usage + +```yaml +- name: Set file system storage + include_tasks: "create_fss.yml" + when: use_fss + diff --git a/ocne2/docs/create_instance.md b/ocne2/docs/create_instance.md new file mode 100644 index 0000000..52c310c --- /dev/null +++ b/ocne2/docs/create_instance.md @@ -0,0 +1,83 @@ +# create_instance.yml — Orchestration for OCI Environment Provisioning + +This is the top-level Ansible playbook that orchestrates network, compute, security, storage, and (optionally) Kubernetes cluster deployment on Oracle Cloud Infrastructure (OCI). + +## Purpose + +- Automates the full lifecycle of OCI environment provisioning and teardown, including VCN, subnets, security lists, compute instances, block storage, and file storage. +- Manages variables, facts, and inventory to ensure correct resource creation and cross-playbook dependencies. +- Integrates generation and inclusion of dynamic config files and security rules using Jinja2 templates. + +## Structure + +- Multi-section playbook: + 1. **Gather facts and create instances:** (localhost) + Gathers config, creates network (VCN, subnet, security), discovers compartment, generates variables, and sets up required resources using templates and includes (ingress/egress rules, oci_vars, block storage). + 2. **Configure new instances:** (hosts: all) + Prepares host environment (users, SSH, provisioning, etc.) via `host_setup.yml`. + 3. **Update all packages:** + Optionally runs `update_all_rpms.yml` for system updates and reboots. + 4. **Install Oracle Cloud Native Environment:** + Deploys Oracle CNE variant using imported playbooks by type (e.g., `deploy_ocne_libvirt.yml`). + 5. **Provision Podman and container tools:** + Optionally installs Podman-related tooling via `provision_podman.yml`. + 6. **Print instance details:** + Outputs final connection details and enables manual review. + 7. **Teardown:** + Removes all provisioned OCI resources if required, using `delete_fss.yml` and OCI module state=absent. + +## Requirements + +- Oracle OCI Ansible Collection (`oracle.oci`) and all collections in `requirements.yml` +- Detailed configuration in `default_vars.yml` and optionally in `oci_vars.yml` +- SSH keypair available on localhost for instance bootstrapping +- Optional: Configuration for use of FSS, Podman, or advanced OCNE deployment (via variables) + +## Key Included/Imported Files + +- `default_vars.yml`: Defaults for all core variables +- `block.yml`: Block storage attachment +- `build.yml`: Compute instance deployment logic (looped for each instance) +- `create_fss.yml` and `delete_fss.yml`: FSS provisioning/teardown +- `host_setup.yml`: User, SSH, and system prep per new instance +- `update_all_rpms.yml`: Updates and reboots (optional) +- `deploy_ocne_libvirt.yml`, `deploy_ocne_oci.yml`, `deploy_ocne_none.yml`: Cluster deployment logic, selected by variable +- Jinja2 templates: + - `ingress_security_rules.j2`, `egress_security_rules.j2` (network rules) + - `oci_vars.j2`, `fss_vars.j2` (variable output) + - `fss_pv.j2`, `fss_pvc.j2`, `fss_pod.j2` (K8s storage manifests) + +## Major Variables + +See `default_vars.yml` for base values. Some important examples: + +| Variable | Description | +| --- | --- | +| `compute_instances` | Dictionary of instance configs, for host loop | +| `use_fss` | Toggle for File Storage Service usage | +| `ocne_type` | Determines which Oracle CNE deployment is installed, via these playbooks:`deploy_ocne_libvirt.yml`, `deploy_ocne_oci.yml`, `deploy_ocne_none.yml` | +| `update_all` | If true, all packages are updated/rebooted | +| ... | Many others; see playbook, defaults, and comments | + +## Relationships + +- **Orchestration root:** Triggers almost all file logic in `/ocne2` +- **Dynamic includes:** Adapts workflow based on feature flags (FSS, Podman, OCNE type) +- **Reads/generated output:** Inventory facts, variable YAML, K8s manifests for storage +- **Handles teardown and cleanup:** Ensures no orphaned cloud resources + +## References + +- [OCI Ansible Collection Documentation](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/) +- [Ansible User Guide](https://docs.ansible.com/ansible/latest/index.html) + + + +To customize, adjust variables in `default_vars.yml` and inventory as appropriate. + diff --git a/ocne2/docs/default_vars.md b/ocne2/docs/default_vars.md new file mode 100644 index 0000000..04c6b79 --- /dev/null +++ b/ocne2/docs/default_vars.md @@ -0,0 +1,69 @@ +# default_vars.yml — Documentation + +## Purpose + +Defines all primary variables for playbook-driven creation, configuration, and deployment of resources in Oracle Cloud Infrastructure (OCI) and for the Oracle Cloud Native Environment (Oracle CNE) stack. These defaults control instance shapes, user access, block storage, cluster provisioning, and feature toggles. + +## Variable Breakdown + +### Compute Instance Parameters + +- **compute_instances:** + Dictionary mapping instance numbers to specifications: + - `instance_name`: Name of the VM (e.g. `"ocne"`, `"ol-node-01"`, etc.) + - `type`: Role or group (e.g. `"server"` or `"client"`) + - `boot_volume_size_in_gbs`: Size of the boot volume (GB) + +- **os / os_version:** + Determines the Oracle Linux version used by the deployed compute instance. Valid values are: `"8"`, `"9"` or `"10"` + +- **instance_shape / instance_ocpus / instance_memory:** + OCI shape specifiers (shape name (`instance_shape:`), vCPUs (`instance_cpus:`), memory in GB (`instance_memory:`), etc.). + +- **`subnet_cidr_block:`** + CIDR for the subnet into which VMs are placed. + +### User and Access + +- **`username:`**: Default user ("oracle") +- **`usergroup:`**: User's group (defaults to username) +- **`user_default_password:`**: Initial password for the user +- **`debug_enabled:`**: Toggle for additional debug output + +### Block Storage Controls + +- **`add_block_storage:`** Enable/disable extra block volume addition +- **`block_volume_size_in_gbs:`** Size per block volume +- **`block_count:`** Number of block volumes to attach + +### Networking and Load Balancing + +- **`use_ingress_lb:`** Enable/disable use of an ingress load balancer + +### OCNE Cluster and Features + +- **`ocne_type:`** Cluster type for Oracle CNE deployment (e.g. "libvirt") +- **`install_ocne_rpm:`** Install Oracle CNE RPM packages if set true +- **`create_ocne_cluster:`** Toggle overall Oracle CNE cluster creation +- **`create_ocne_oci_cluster:`** Toggle creation of an Oracle CNE cluster in OCI +- **`debug_oci_cluster:`** Enable debugging for cluster creation +- **`ocne_cluster_node_options:`** Additional CLI node options +- **`ocne_cluster_name:`** Name assigned to the OCI cluster +- **`num_cp_nodes:` / `num_wk_nodes:`** Number of Control-plane and Worker nodes + +### Other Feature Flags + +- **`update_all:`** Toggle for updating all packages with RPMs +- **`use_fss:`** Enable/disable FSS (File Storage Service) provisioning +- **`use_podman:`** Enable/disable Podman/container tooling installation + +### Miscellaneous + +- **`oci_yum_region:`** (Commented) Optionally specifies the regional YUM repository for package management + +## Notes + +- Toggling these variables enables or disables major playbook features and deployment flows. +- These defaults can be overridden via vars_files or set directly on the command line. +- Designed for use across all playbooks in the `ocne2` automation stack. + diff --git a/ocne2/docs/delete_fss.md b/ocne2/docs/delete_fss.md new file mode 100644 index 0000000..986fe6a --- /dev/null +++ b/ocne2/docs/delete_fss.md @@ -0,0 +1,43 @@ +# delete_fss.yml — Teardown Oracle Cloud File Storage Service (FSS) + +This playbook performs safe teardown of any previously-provisioned OCI File Storage Service (FSS) resources, including the export, mount target, and file system objects. + +## Purpose + +- Ensures all FSS-related resources are fully removed (state=absent). +- Prevents cloud resource leaks and potential unexpected charges. +- Typically included as a teardown or cleanup step from a parent playbook (e.g., `create_instance.yml`). + +## Requirements + +- Oracle OCI Ansible Collection (`oracle.oci`). +- Variables set from the provisioning stage: + - `export_id`, `mount_target_id`, `file_system_id`. + +## Main Tasks + +1. **Delete Export:** + Removes the NFS export from the given FSS. +2. **Delete Mount Target:** + Cleans up the mount target, breaking NFS client connectivity. +3. **Delete File System:** + Removes the primary network file system container. + +## Relationships + +- **Teardown phase:** Called by `create_instance.yml` during environment teardown, if `use_fss` is enabled. +- **Depends on:** Variable facts produced by `create_fss.yml`. + +## Reference + +- [oracle.oci.oci_file_storage_export](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_file_storage_export_module.html) +- [oracle.oci.oci_file_storage_mount_target](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_file_storage_mount_target_module.html) +- [oracle.oci.oci_file_storage_file_system](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/5.5.0/collections/oracle/oci/oci_file_storage_file_system_module.html) + +## Example Usage + +```yaml +- name: Delete file system storage + include_tasks: "delete_fss.yml" + when: use_fss + diff --git a/ocne2/docs/deploy_ocne_libvirt.md b/ocne2/docs/deploy_ocne_libvirt.md new file mode 100644 index 0000000..74ec5e4 --- /dev/null +++ b/ocne2/docs/deploy_ocne_libvirt.md @@ -0,0 +1,54 @@ +# deploy_ocne_libvirt.yml — Deploy OCNE on Local KVM/Libvirt Node + +This playbook installs Oracle Cloud Native Environment (Oracle CNE) on a KVM/Libvirt-backed Oracle Linux server. + +## Purpose + +- Installs necessary virtualization packages for Oracle Linux 8/9 (KVM, libvirt, cockpit, containers). +- (Optionally) Installs Oracle CNE and creates a cluster using distribution-recommended repositories and tools. +- Creates a user and configures SSH, sudo, and firewall to enable local hypervisor control. + +## Requirements + +- Target hosts: Oracle Linux 8 or 9 "server" group members. +- SSH setup, user with sudo privileges (`username`/`user_default_password`). +- Variables from `default_vars.yml` and playbook scope. +- Optionally, `install_ocne_rpm`, `create_ocne_cluster`, `ocne_cluster_name`. + +## Key Tasks + +1. **Install virtualization packages:** + Installs base packages (KVM, libvirt, virt-install, cockpit, etc.) with retry logic based on OS version. + +2. **Enable and start services:** + Handles switching between Oracle Linux 8 (monolithic) and 9 (modular) systemd service layouts. + +3. **Add user to virtualization groups:** + Ensures proper permissions for `libvirt`/`qemu`. + +4. **Repository enable/block:** + If `install_ocne_rpm` is enabled, configures extra Oracle Linux repositories for Oracle CNE. + +5. **Install OCNE & cluster tools:** + Installs Oracle CNE/kubectl and (optionally) calls `ocne cluster start` to set up a cluster. + +## Relationships + +- **Deployed from:** `create_instance.yml` for `ocne_type: libvirt` +- **Shares pattern/logical roles with:** `deploy_ocne_oci.yml` (OCI-based) and `deploy_ocne_none.yml` (noop path) +- **Variables sourced from:** Host/group/fact files, `default_vars.yml` + +## References + +- [Oracle CNE Documentation](https://docs.oracle.com/en/solutions/deploy-cloud-native-environments/index.html) +- [Libvirt Documentation](https://libvirt.org/) +- [oracle.oci.oci_compute_instance](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/) + +## Example Usage + + + +This playbook is typically executed as part of the full workflow via `create_instance.yml`. + diff --git a/ocne2/docs/deploy_ocne_none.md b/ocne2/docs/deploy_ocne_none.md new file mode 100644 index 0000000..933255a --- /dev/null +++ b/ocne2/docs/deploy_ocne_none.md @@ -0,0 +1,33 @@ +# deploy_ocne_none.yml — No-Operation Oracle CNE Playbook + +This playbook provisions an Oracle Linux 8 or 9 environment fully configured and ready for an Oracle Cloud Native Environment (Oracle CNE) 2 deployment. This is used when a pre-configured Oracle CNE 2 cluster installation is not desired or needed, allowing the user to perform a manual install of Oracle CNE 2 of their choice. + +## Purpose + +- Serves as an explicit no-operation scenario for environments or test runs where Oracle CNE deployment should be skipped. +- Ensures the provisioning workflow is consistent, regardless of whether Oracle CNE is actually being installed. + +## Requirements + +- None beyond the Ansible runtime; this playbook simply outputs a message at execution. + +## Main Task + +- **Prints noop message:** + Outputs a message stating that no Oracle CNE cluster is deployed and no changes have been made. + +## Relationships + +- **Selected by:** The main orchestration playbook (`create_instance.yml`) when `ocne_type: none` or equivalent is set. +- **Complements:** `deploy_ocne_libvirt.yml`, `deploy_ocne_oci.yml` + +## Example Output + +When run, this playbook will produce: + +```yaml +TASK [Print noop message] +ok: [localhost] => { + "msg": "This is a noop and does not deploy OCNE." +} + diff --git a/ocne2/docs/deploy_ocne_oci.md b/ocne2/docs/deploy_ocne_oci.md new file mode 100644 index 0000000..f5f8e5d --- /dev/null +++ b/ocne2/docs/deploy_ocne_oci.md @@ -0,0 +1,64 @@ +# deploy_ocne_oci.yml — Deploy Oracle CNE Cluster on Oracle Cloud Infrastructure + +This playbook provisions and configures an Oracle Cloud Native Environment (Oracle CNE) cluster directly on Oracle Cloud Infrastructure (OCI), including object storage and custom configuration. + +## Purpose + +- Automates virtualization environment setup for both Oracle Linux 8 and 9. +- Installs and configures Oracle CNE, including repositories, CLI, and supporting components. +- Generates OCI and Kubernetes cluster configuration for direct use with OCI resources. +- Manages object storage (OCI buckets) for images, config, and cluster persistence. +- Optionally deploys File Storage Service (FSS) resources if enabled. + +## Requirements + +- Targets one or more inventory hosts in the "server" group. +- OS: Oracle Linux 8 or 9. Uses root or sudo-privileged `username`. +- Variables set in `default_vars.yml` and (optional) `oci_vars.yml` for custom resource handling. +- `oracle.oci` collection and other dependencies from `requirements.yml`. + +## Key Tasks + +1. **Install virtualization packages:** + Installs KVM/libvirt/cockpit, with logic for both Oracle Linux 8 and 9. + +2. **Start and enable services:** + Ensures all needed sockets/services are enabled (modular or monolithic layout). + +3. **Install Oracle CNE repositories, CLI, and dependencies:** + Adds all required YUM repositories, enables Oracle CNE and developer repos, and installs `ocne`, `kubectl`, Python CLI. + +4. **Configure OCI environment:** + Copies and edits OCI config files, keys (in `~/.oci/`) for automation. + +5. **Create object storage bucket:** + Provisions an OCI object storage bucket as image and config store for cluster lifecycle. + +6. **Generate cluster YAML config:** + Assembles a custom configuration for Oracle CNE using current variable values and cloud resource references. + +7. **Deploy FSS deployment descriptors:** + Conditionally generates persistent volume and pod descriptors for Kubernetes when `use_fss` is set. + +8. **Cluster provisioning:** + Calls Oracle CNE CLI to launch the cluster using final config. + +## Relationships + +- **Triggered by:** `create_instance.yml` when `ocne_type: oci` +- **Shares structure with:** `deploy_ocne_libvirt.yml` (local cluster) and `deploy_ocne_none.yml` (noop) +- **Imports:** Supporting roles/tasks, including `fss_deployments.yml` for storage + +## References + +- [OCI Ansible Collection](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/) +- [Oracle CNE Documentation](https://docs.oracle.com/en/solutions/deploy-cloud-native-environments/index.html) +- [oracle.oci.oci_object_storage_bucket](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/) + +## Example Usage + +This playbook is executed automatically as part of the Oracle CNE cluster deployment when the correct type is selected in the main playbook (`create_instance.yml`), but may also be run directly for advanced scenarios: + + + diff --git a/ocne2/docs/fss_deployments.md b/ocne2/docs/fss_deployments.md new file mode 100644 index 0000000..1b67e59 --- /dev/null +++ b/ocne2/docs/fss_deployments.md @@ -0,0 +1,48 @@ +# fss_deployments.yml — Create FSS-backed Kubernetes Resources + +This playbook generates Kubernetes deployment manifests (PersistentVolume, PersistentVolumeClaim, Pod) for use with Oracle Cloud File Storage Service (FSS) as persistent backend storage. + +## Purpose + +- Dynamically generates the Kubernetes YAML resources needed to mount and consume FSS storage in a K8s cluster. +- Provides bridge logic between OCI-provisioned FSS and applications running in Kubernetes. + +## Requirements + +- Variable file (`fss_vars.yml`) rendered by previous FSS provisioning. +- Jinja2 templates: `fss_pv.j2`, `fss_pvc.j2`, `fss_pod.j2`. +- Typically run within the context of a larger Oracle CNE or Kubernetes deployment scenario. + +## Main Tasks + +1. **Include FSS variables:** + Loads the YAML with vital identifiers rendered during FSS provisioning. + +2. **Render Kubernetes resources:** + Uses Jinja2 templates to create files: + - `fss-pv.yaml`: PersistentVolume bound to FSS + - `fss-pvc.yaml`: PersistentVolumeClaim for Pod usage + - `fss-pod.yaml`: Demonstration/test pod configured to mount the PVC + +3. **Permissions:** + All files are owned by the relevant user and given ready-to-consume permissions for deployment (`kubectl apply -f ...`). + +## Relationships + +- **Produces:** Artifacts for K8s cluster deployment of FSS-backed storage. +- **Used by:** `deploy_ocne_oci.yml` and other playbooks when storage integration is required. +- **Consumes:** Output of `create_fss.yml` and Jinja2 templates. + +## References + +- [Kubernetes Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) +- [OCI FSS CSI Driver](https://github.com/oracle/oci-cloud-controller-manager/blob/master/docs/flexvolume/flexvolume.md) + +## Example Output + +After execution, the following files will exist for deployment: + +- `~/fss-pv.yaml` +- `~/fss-pvc.yaml` +- `~/fss-pod.yaml` + diff --git a/ocne2/docs/host_setup.md b/ocne2/docs/host_setup.md new file mode 100644 index 0000000..041d259 --- /dev/null +++ b/ocne2/docs/host_setup.md @@ -0,0 +1,56 @@ +# host_setup.yml — Configure Instance OS for OCI & Kubernetes + +This playbook prepares newly-provisioned OCI compute instances for secure automation, SSH access, and Kubernetes/operator readiness. + +## Purpose + +- Automates core Linux setup and hardening for Ansible and operations team management. +- Ensures all necessary OS-level configuration and user access for cluster or application workloads. + +## Main Tasks + +1. **Handle connectivity/retry logic:** + Waits for SSH access and performs retry logic to handle slow cloud bootstraps. + +2. **Setup facts/locale:** + Collects system info, grows root filesystem, and sets up shell locale. + +3. **User management:** + Creates a privileged user (`username`), adds SSH keys, and enables password-less sudo. + +4. **SSH key management:** + Generates new SSH keypair, distributes authorized keys for password-less intra-cluster access. + +5. **Inventory/host information:** + Prints variables and host inventory when debugging is enabled. + +6. **Firewall/basics:** + Opens firewall, logs denied packets (if debugging), accepts/records new SSH fingerprints for all hosts. + +7. **Rescue/retry:** + If a setup step fails, the playbook retries up to `max_retries` times before aborting. + +## Requirements + +- Linux instance booted on OCI, accessible via generated private key. +- Variables: `username`, `user_default_password`, others from `default_vars.yml`. +- Ansible/SSH access from the orchestrating host. + +## Relationships + +- **Run by:** `create_instance.yml` for all active inventory hosts. +- **Populates:** SSH setup and Ansible workspace for downstream provisioning. + +## References + +- [Ansible user module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/user_module.html) +- [Ansible authorized_key module](https://docs.ansible.com/ansible/latest/collections/ansible/posix/authorized_key_module.html) + +## Example Usage + +Called for each deployed VM in the main orchestration: + +```yaml +- name: Configure instance + include_tasks: "host_setup.yml" + diff --git a/ocne2/docs/provision_podman.md b/ocne2/docs/provision_podman.md new file mode 100644 index 0000000..934d03f --- /dev/null +++ b/ocne2/docs/provision_podman.md @@ -0,0 +1,42 @@ +# provision_podman.yml — Install Podman and Container Tools + +This playbook installs the required container tooling on OCI compute instances, supporting modern OCI-based development and Kubernetes workflows using Podman. + +## Purpose + +- Installs Podman and related tools on Oracle Linux 8 or 9. +- Ensures containerization support for running application containers or deploying with Kubernetes on provisioned hosts. + +## Requirements + +- Target hosts: Oracle Linux 8 or 9 in the `server` group. +- Variables set in `default_vars.yml`. +- `ansible.posix` and relevant collections in `requirements.yml`. + +## Main Tasks + +1. **Check OS version:** + Selects the correct package group or list for Oracle Linux 8 vs 9. + +2. **Install packages:** + - Oracle Linux 8: Installs the `@container-tools:ol8` group, conntrack, curl. + - Oracle Linux 9: Installs podman, podman-docker, conntrack, curl. + +## Relationships + +- **Feature flag:** Controlled by `use_podman` in `default_vars.yml`. +- **Run from:** The main orchestration playbook (`create_instance.yml`) if enabled. + +## References + +- [Podman Documentation](https://podman.io/) +- [Containers on Oracle Linux](https://docs.oracle.com/en/operating-systems/oracle-linux/podman/index.html) +- [Ansible dnf module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/dnf_module.html) + +## Example Usage + +```yaml +- name: Provision Podman and Container Tools + import_playbook: provision_podman.yml + when: use_podman + diff --git a/ocne2/docs/requirements.md b/ocne2/docs/requirements.md new file mode 100644 index 0000000..6f2115c --- /dev/null +++ b/ocne2/docs/requirements.md @@ -0,0 +1,39 @@ +# requirements.yml — Ansible Collection Dependencies + +This file specifies all the required Ansible Galaxy collections needed to support the automation, OCI, OS, cryptography, and infrastructure features used by the playbooks in this project. + +## Purpose + +- Ensures that all playbooks have access to the correct modules, plugins, and roles available from Ansible Galaxy. +- Provides a version-locking and reproducible installation method for third-party code dependencies. + +## Major Collections + +| Collection | Modules Used/Features | +|-----------------------------------|-----------------------------------------| +| ansible.posix | Filesystem, authorized_key, command | +| community.general | Utility plugins, ini lookup, random_str | +| community.crypto | OpenSSH keypair generation, cryptotasks | +| freeipa.ansible_freeipa | Optional, for FreeIPA integration | +| community.libvirt | Libvirt/KVM resource management | +| oracle.oci | Core OCI resource automation modules | +| ovirt.ovirt | Ovirt virtualization management | +| community.postgresql | Postgres support (optional) | + +## Example Usage + +Install all required dependencies: + +```bash +ansible-galaxy collection install -r requirements.yml +``` + +## Relationships + +- **Required by:** All Ansible playbooks in this OCNE/OCI automation stack. +- **Referenced in:** Setup/onboarding guides, `README.md`. + +## Additional Information + +For specific collection docs and supported modules, see the [Ansible Galaxy documentation](https://docs.ansible.com/ansible/latest/collections/index.html). + diff --git a/ocne2/docs/update_all_rpms.md b/ocne2/docs/update_all_rpms.md new file mode 100644 index 0000000..6f2115c --- /dev/null +++ b/ocne2/docs/update_all_rpms.md @@ -0,0 +1,39 @@ +# requirements.yml — Ansible Collection Dependencies + +This file specifies all the required Ansible Galaxy collections needed to support the automation, OCI, OS, cryptography, and infrastructure features used by the playbooks in this project. + +## Purpose + +- Ensures that all playbooks have access to the correct modules, plugins, and roles available from Ansible Galaxy. +- Provides a version-locking and reproducible installation method for third-party code dependencies. + +## Major Collections + +| Collection | Modules Used/Features | +|-----------------------------------|-----------------------------------------| +| ansible.posix | Filesystem, authorized_key, command | +| community.general | Utility plugins, ini lookup, random_str | +| community.crypto | OpenSSH keypair generation, cryptotasks | +| freeipa.ansible_freeipa | Optional, for FreeIPA integration | +| community.libvirt | Libvirt/KVM resource management | +| oracle.oci | Core OCI resource automation modules | +| ovirt.ovirt | Ovirt virtualization management | +| community.postgresql | Postgres support (optional) | + +## Example Usage + +Install all required dependencies: + +```bash +ansible-galaxy collection install -r requirements.yml +``` + +## Relationships + +- **Required by:** All Ansible playbooks in this OCNE/OCI automation stack. +- **Referenced in:** Setup/onboarding guides, `README.md`. + +## Additional Information + +For specific collection docs and supported modules, see the [Ansible Galaxy documentation](https://docs.ansible.com/ansible/latest/collections/index.html). + From b2442c6aa5a52a62ed43adde6f689f526453fa6a Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Thu, 18 Dec 2025 15:15:28 +0000 Subject: [PATCH 05/10] Create the Templates directory and add the docs for the Jinja2 templates --- .../templates/egress_security_rules.j2.md | 42 ++++++++++++++++ ocne2/docs/templates/fss_pod.j2.md | 48 +++++++++++++++++++ ocne2/docs/templates/fss_pv.j2.md | 48 +++++++++++++++++++ ocne2/docs/templates/fss_pvc.j2.md | 42 ++++++++++++++++ ocne2/docs/templates/fss_vars.j2.md | 38 +++++++++++++++ .../templates/ingress_security_rules.j2.md | 43 +++++++++++++++++ ocne2/docs/templates/oci_vars.j2.md | 35 ++++++++++++++ 7 files changed, 296 insertions(+) create mode 100644 ocne2/docs/templates/egress_security_rules.j2.md create mode 100644 ocne2/docs/templates/fss_pod.j2.md create mode 100644 ocne2/docs/templates/fss_pv.j2.md create mode 100644 ocne2/docs/templates/fss_pvc.j2.md create mode 100644 ocne2/docs/templates/fss_vars.j2.md create mode 100644 ocne2/docs/templates/ingress_security_rules.j2.md create mode 100644 ocne2/docs/templates/oci_vars.j2.md diff --git a/ocne2/docs/templates/egress_security_rules.j2.md b/ocne2/docs/templates/egress_security_rules.j2.md new file mode 100644 index 0000000..e5b09c4 --- /dev/null +++ b/ocne2/docs/templates/egress_security_rules.j2.md @@ -0,0 +1,42 @@ +# egress_security_rules.j2 — Jinja2 Template for Security List Egress Rules + +This Jinja2 template generates a YAML variable file defining egress (outbound) security rules used in OCI network Security Lists for new compute and application instances. + +## Purpose + +- Outputs a structure (`instance_egress_security_rules`) used to configure which outbound ports and protocols are permitted on each instance subnet. +- Used to restrict or allow traffic, controlling NFS, general access, and K8s/FSS integration. + +## Input Variables + +| Variable | Description | +|--------------|--------------------------------------------| +| `use_fss` | Enables additional FSS traffic rules | + +## Logic + +- By default, allows outgoing TCP traffic to anywhere (0.0.0.0/0). +- If `use_fss` is true, adds dynamic rules for NFS ports/protocols used by OCI FSS and Kubernetes workloads. + +## Main Output + +- `instance_egress_security_rules`: List of egress security rule dictionaries, ready for inclusion with OCI Ansible modules. + +## Relationships + +- **Rendered by:** `create_instance.yml` using `template` module. +- **Consumed by:** OCI security list tasks when creating subnets and firewall rules. + +## Example Output + +```yaml +instance_egress_security_rules: + - destination: "0.0.0.0/0" + protocol: 6 + - destination: "10.0.0.0/24" + protocol: 6 + tcp_options: + source_port_range: + max: 111 + min: 111 + diff --git a/ocne2/docs/templates/fss_pod.j2.md b/ocne2/docs/templates/fss_pod.j2.md new file mode 100644 index 0000000..3db96d8 --- /dev/null +++ b/ocne2/docs/templates/fss_pod.j2.md @@ -0,0 +1,48 @@ +# fss_pod.j2 — Jinja2 Template for FSS Test Pod (Kubernetes) + +This Jinja2 template generates a Kubernetes Pod manifest configured to mount a PersistentVolumeClaim backed by Oracle Cloud File Storage Service (FSS). + +## Purpose + +- Demonstrates/test access to an NFS-backed PersistentVolumeClaim in a K8s cluster. +- Intended to run a simple log-producing process to verify storage integration. + +## Input Variables + +- No explicit variables beyond what is expected to be rendered by fss_pvc.j2 and upstream FSS provision logic. + +## Main Output + +A Kubernetes Pod manifest (`fss-pod.yaml`) with: + +- Use of official Oracle Linux 8 container image +- `/data` mount path for persistent storage +- Writes a timestamp to `/data/out.txt` in an infinite loop + +## Relationships + +- **Rendered by:** `fss_deployments.yml` +- **Depends on:** PVC defined in `fss_pvc.j2` (claimName: fss-pvc) +- **Used with:** OCI FSS CSI driver, example/test deployment after storage provisioning + +## Example Output (excerpt) + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: app +spec: + containers: + - name: app + image: ghcr.io/oracle/oraclelinux:8 + command: ["/bin/bash"] + args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 5; done"] + volumeMounts: + - name: persistent-storage + mountPath: /data + volumes: + - name: persistent-storage + persistentVolumeClaim: + claimName: fss-pvc + diff --git a/ocne2/docs/templates/fss_pv.j2.md b/ocne2/docs/templates/fss_pv.j2.md new file mode 100644 index 0000000..3db96d8 --- /dev/null +++ b/ocne2/docs/templates/fss_pv.j2.md @@ -0,0 +1,48 @@ +# fss_pod.j2 — Jinja2 Template for FSS Test Pod (Kubernetes) + +This Jinja2 template generates a Kubernetes Pod manifest configured to mount a PersistentVolumeClaim backed by Oracle Cloud File Storage Service (FSS). + +## Purpose + +- Demonstrates/test access to an NFS-backed PersistentVolumeClaim in a K8s cluster. +- Intended to run a simple log-producing process to verify storage integration. + +## Input Variables + +- No explicit variables beyond what is expected to be rendered by fss_pvc.j2 and upstream FSS provision logic. + +## Main Output + +A Kubernetes Pod manifest (`fss-pod.yaml`) with: + +- Use of official Oracle Linux 8 container image +- `/data` mount path for persistent storage +- Writes a timestamp to `/data/out.txt` in an infinite loop + +## Relationships + +- **Rendered by:** `fss_deployments.yml` +- **Depends on:** PVC defined in `fss_pvc.j2` (claimName: fss-pvc) +- **Used with:** OCI FSS CSI driver, example/test deployment after storage provisioning + +## Example Output (excerpt) + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: app +spec: + containers: + - name: app + image: ghcr.io/oracle/oraclelinux:8 + command: ["/bin/bash"] + args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 5; done"] + volumeMounts: + - name: persistent-storage + mountPath: /data + volumes: + - name: persistent-storage + persistentVolumeClaim: + claimName: fss-pvc + diff --git a/ocne2/docs/templates/fss_pvc.j2.md b/ocne2/docs/templates/fss_pvc.j2.md new file mode 100644 index 0000000..9e339b4 --- /dev/null +++ b/ocne2/docs/templates/fss_pvc.j2.md @@ -0,0 +1,42 @@ +# fss_pvc.j2 — Jinja2 Template for FSS PersistentVolumeClaim (Kubernetes) + +This Jinja2 template generates a Kubernetes PersistentVolumeClaim (PVC) manifest, which binds to an FSS-backed PersistentVolume for use by cluster workloads. + +## Purpose + +- Allows application pods to request and consume persistent storage provisioned and managed using Oracle Cloud FSS. +- Ensures decoupling of application and storage layers with flexible volume configuration. + +## Input Variables + +- References the PV created by `fss_pv.j2` (volumeName: fss-pv) + +## Main Output + +- Kubernetes PersistentVolumeClaim YAML (`fss-pvc.yaml`) + - Standard `ReadWriteMany` access + - Size and class match the FSS backend + - Binds explicitly to the `fss-pv` volume + +## Relationships + +- **Rendered by:** `fss_deployments.yml` alongside PV and pod resources +- **Claimed by:** Pods such as those generated from `fss_pod.j2` +- **Depends on:** FSS PV manifest defined by `fss_pv.j2` + +## Example Output + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: fss-pvc +spec: + accessModes: + - ReadWriteMany + storageClassName: "" + resources: + requests: + storage: 50Gi + volumeName: fss-pv + diff --git a/ocne2/docs/templates/fss_vars.j2.md b/ocne2/docs/templates/fss_vars.j2.md new file mode 100644 index 0000000..7ada2a4 --- /dev/null +++ b/ocne2/docs/templates/fss_vars.j2.md @@ -0,0 +1,38 @@ +# fss_vars.j2 — Jinja2 Template for FSS Provisioning Output + +This simple Jinja2 template renders a YAML file of variables that define the key facts for an OCI File Storage Service (FSS) deployment. + +## Purpose + +- Produces a YAML document of FSS resource identifiers and connection information. +- Used to pass outputs from Ansible FSS provisioning to downstream deployments (Kubernetes, Helm, templated manifests). + +## Input Variables + +| Variable | Description | +|-------------------------|---------------------------------------| +| file_system_id | OCID of the networked file system | +| mount_target_ip_address | Private mount target IP address | +| export_path | Exported NFS path for mounting | + +## Main Output + +Typical YAML output (`fss_vars.yml`) for inclusion/consumption: + +```yaml +file_system_id: +mount_target_ip_address: +export_path: +``` + +## Relationships + +- **Rendered by:** `create_fss.yml` at the end of FSS provisioning +- **Consumed by:** `fss_deployments.yml` for rendering manifest templates +- **Feeds variables to:** `fss_pv.j2`, `fss_pvc.j2`, `fss_pod.j2` + +## Example Usage + +After provisioning the FSS stack, this variable file is referenced by +`include_vars` to inject facts throughout the deployment chain. + diff --git a/ocne2/docs/templates/ingress_security_rules.j2.md b/ocne2/docs/templates/ingress_security_rules.j2.md new file mode 100644 index 0000000..15b9918 --- /dev/null +++ b/ocne2/docs/templates/ingress_security_rules.j2.md @@ -0,0 +1,43 @@ +# ingress_security_rules.j2 — Jinja2 Template for Security List Ingress Rules + +This Jinja2 template generates a YAML variable file defining ingress (inbound) security rules for OCI Security Lists, tailored for SSH access, web traffic, and NFS/FSS use cases. + +## Purpose + +- Defines rules for which inbound connections are permitted to cloud instances. +- Supports optional activation of load balancer and FSS-specific ports via variables. + +## Input Variables + +| Variable | Description | +|------------------|---------------------------------------------------| +| `use_ingress_lb` | Enables HTTP/HTTPS (80/443) load balancer rules | +| `use_fss` | Enables FSS NFS/port rules | + +## Logic + +- Always allows inbound SSH (port 22, TCP) from anywhere. +- If `use_ingress_lb` is true, opens ports 80 and 443 for web load balancer traffic. +- If `use_fss` is true, adds multiple port/protocol combinations for NFS and FSS integration. + +## Main Output + +- `instance_ingress_security_rules`: List of dictionary entries, consumed by OCI network configuration tasks. + +## Relationships + +- **Rendered by:** `create_instance.yml` with the `template` module. +- **Consumed by:** Security list creation tasks when new subnets are provisioned. + +## Example Output + +```yaml +instance_ingress_security_rules: + - source: "0.0.0.0/0" + protocol: 6 + tcp_options: + destination_port_range: + max: 22 + min: 22 + # Ports 80/443 and NFS rules added when variables are true + diff --git a/ocne2/docs/templates/oci_vars.j2.md b/ocne2/docs/templates/oci_vars.j2.md new file mode 100644 index 0000000..a0ae677 --- /dev/null +++ b/ocne2/docs/templates/oci_vars.j2.md @@ -0,0 +1,35 @@ +# oci_vars.j2 — Jinja2 Template for OCI Resource Variable Output + +This template renders a YAML snippet containing essential OCI resource identifiers for use throughout the automation project. + +## Purpose + +- Serializes core environment variables for easy inclusion and referencing in downstream Ansible tasks and playbooks. +- Consolidates compartment, VCN, and subnet IDs and domain names into a single file. + +## Input Variables + +| Variable | Description | +|-------------------------|-------------------------------------| +| my_compartment_id | OCID of target compartment | +| my_vcn_id | OCID of Virtual Cloud Network | +| my_subnet_id | OCID of target subnet | +| my_subnet_domain_name | Domain name of provisioned subnet | + +## Main Output + +A YAML file (e.g., `oci_vars.yml`) containing references to the constants above, which are then loaded where needed (e.g., with `include_vars`, or as direct file inclusion). + +## Relationships + +- **Rendered by:** `create_instance.yml` as part of early provisioning +- **Consumed by:** Playbooks like `deploy_ocne_oci.yml` and others that require networking or compartment context + +## Example Output + +```yaml +my_compartment_id: ocid1.compartment.oc1..exampleuniqueID +my_vcn_id: ocid1.vcn.oc1..exampleuniqueID +my_subnet_id: ocid1.subnet.oc1..exampleuniqueID +my_subnet_domain_name: subnet.example.oraclevcn.com + From 38705583705aee34079ebd18579862d9da50cfd4 Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Mon, 5 Jan 2026 10:42:26 +0000 Subject: [PATCH 06/10] Add the Version 1 of the Documentation for the following products: OCNE 1, Oracle Linux, Oracle Linux Virtualization Manager and Oracle Linux Automation Maanger --- labs/docs/README.md | 29 +++ labs/docs/olam-hello-world.md | 31 +++ ocne/docs/README copy.md | 228 ++++++++++++++++++ ocne/docs/README.md | 3 + ocne/docs/build.md | 61 +++++ ocne/docs/ceph_deployments.md | 45 ++++ ocne/docs/create_fss.md | 48 ++++ ocne/docs/create_instance.md | 70 ++++++ ocne/docs/create_lb.md | 48 ++++ ocne/docs/create_ocir.md | 42 ++++ ocne/docs/create_vlan.md | 47 ++++ ocne/docs/default_vars.md | 59 +++++ ocne/docs/delete_fss.md | 43 ++++ ocne/docs/delete_lb.md | 37 +++ ocne/docs/delete_ocir.md | 36 +++ ocne/docs/deploy_ocne_compact.md | 49 ++++ ocne/docs/deploy_ocne_full.md | 48 ++++ ocne/docs/deploy_ocne_none.md | 32 +++ ocne/docs/deploy_ocne_quick.md | 48 ++++ ocne/docs/deploy_ocne_vlan.md | 61 +++++ ocne/docs/fss_deployments.md | 43 ++++ ocne/docs/host_assign_vlan_ip.md | 46 ++++ ocne/docs/host_setup.md | 56 +++++ ocne/docs/ol8_repo_config.md | 38 +++ ocne/docs/ol9_repo_config.md | 38 +++ ocne/docs/preconfig_oci_ccm.md | 36 +++ ocne/docs/provision_istio.md | 41 ++++ ocne/docs/provision_kubectl.md | 39 +++ ocne/docs/provision_oci_ccm.md | 45 ++++ ocne/docs/provision_ocne.md | 48 ++++ ocne/docs/pvc.j2.md | 41 ++++ ocne/docs/templates/cluster.j2.md | 51 ++++ .../templates/egress_security_rules.j2.md | 37 +++ ocne/docs/templates/filesystem.j2.md | 48 ++++ ocne/docs/templates/fss_pod.j2.md | 48 ++++ ocne/docs/templates/fss_pv.j2.md | 47 ++++ ocne/docs/templates/fss_pvc.j2.md | 44 ++++ ocne/docs/templates/fss_vars.j2.md | 37 +++ .../templates/ingress_security_rules.j2.md | 73 ++++++ ocne/docs/templates/istio_lb.j2.md | 40 +++ ocne/docs/templates/lb_vars.j2.md | 33 +++ ocne/docs/templates/myenvironment.j2.md | 58 +++++ ocne/docs/templates/oci_vars.j2.md | 40 +++ ocne/docs/templates/ocir_vars.j2.md | 35 +++ ocne/docs/templates/storageclass.j2.md | 46 ++++ ocne/docs/templates/toolbox.j2.md | 78 ++++++ ocne/docs/templates/vm.j2.md | 80 ++++++ ol/docs/README.md | 190 +++++++++++++++ ol/docs/block.md | 36 +++ ol/docs/build.md | 40 +++ ol/docs/create_instance.md | 39 +++ ol/docs/default_vars.md | 28 +++ ol/docs/download_ol_iso.md | 34 +++ ol/docs/host_setup.md | 34 +++ ol/docs/passwordless_setup.md | 30 +++ ol/docs/provision_kvm.md | 33 +++ ol/docs/provision_kvm_vm.md | 37 +++ ol/docs/provision_podman.md | 28 +++ ol/docs/provision_vbox.md | 31 +++ ol/docs/provision_vnc.md | 31 +++ ol/docs/requirements.md | 33 +++ ol/docs/templates/egress_security_rules.j2.md | 24 ++ .../templates/ingress_security_rules.j2.md | 26 ++ ol/docs/templates/oci_vars.j2.md | 27 +++ ol/docs/templates/vm_template.j2.md | 35 +++ ol/docs/update_all_rpms.md | 30 +++ olam/docs/README.md | 193 +++++++++++++++ olam/docs/block.md | 35 +++ olam/docs/build.md | 33 +++ olam/docs/check_instance_available.md | 28 +++ olam/docs/configure_passwordless_ssh.md | 31 +++ olam/docs/convert_ansible_inventory.sh.md | 25 ++ olam/docs/create_instance.md | 31 +++ olam/docs/default_vars.md | 32 +++ olam/docs/deploy_olam_cluster.md | 35 +++ olam/docs/deploy_olam_none.md | 25 ++ olam/docs/deploy_olam_olae.md | 24 ++ olam/docs/deploy_olam_single.md | 31 +++ olam/docs/deploy_olam_v1.md | 30 +++ olam/docs/get_facts.md | 25 ++ olam/docs/provision_builder.md | 31 +++ olam/docs/provision_free_ipa.md | 27 +++ olam/docs/provision_git_server.md | 29 +++ olam/docs/provision_instance_basics.md | 30 +++ olam/docs/provision_kvm.md | 29 +++ olam/docs/provision_pah.md | 28 +++ olam/docs/provision_vnc.md | 29 +++ olam/docs/requirements.md | 33 +++ olam/docs/templates/bindep.txt.j2.md | 26 ++ .../templates/egress_security_rules.j2.md | 28 +++ .../templates/execution_environment.yml.j2.md | 29 +++ olam/docs/templates/hosts.j2.md | 23 ++ .../templates/ingress_security_rules.j2.md | 28 +++ olam/docs/templates/install_ipa.j2.md | 27 +++ olam/docs/templates/nginx.conf.j2.md | 29 +++ olam/docs/templates/nginx.conf_v1.j2.md | 27 +++ olam/docs/templates/oci_vars.j2.md | 27 +++ olam/docs/templates/playbook.yml.j2.md | 27 +++ olam/docs/templates/receptor.conf.j2.md | 29 +++ .../templates/receptor_cluster.conf.j2.md | 28 +++ olam/docs/templates/requirements.txt.j2.md | 25 ++ olam/docs/templates/requirements.yml.j2.md | 26 ++ olam/docs/terminate_instance.md | 28 +++ olam/docs/update_all_rpms.md | 28 +++ olvm/docs/README.md | 191 +++++++++++++++ olvm/docs/build.md | 31 +++ olvm/docs/check_instance_available.md | 28 +++ olvm/docs/configure_passwordless_ssh.md | 30 +++ olvm/docs/configure_secondary_nic.md | 29 +++ olvm/docs/create_block_storage.md | 27 +++ olvm/docs/create_hostfile_secondary_nic.md | 26 ++ olvm/docs/create_instance.md | 30 +++ olvm/docs/create_vlan.md | 28 +++ olvm/docs/default_vars.md | 28 +++ olvm/docs/ovirt_add_hosts.md | 27 +++ olvm/docs/ovirt_add_logical_network.md | 26 ++ olvm/docs/ovirt_add_storage_domain.md | 27 +++ olvm/docs/ovirt_check_hosts.md | 25 ++ olvm/docs/ovirt_connection_test.md | 25 ++ olvm/docs/ovirt_create_vm_from_template.md | 27 +++ olvm/docs/ovirt_delete_host.md | 26 ++ olvm/docs/ovirt_import_template.md | 26 ++ olvm/docs/ovirt_list_hosts.md | 25 ++ olvm/docs/provision_instance_basics.md | 29 +++ olvm/docs/provision_olvm_engine.md | 27 +++ olvm/docs/provision_olvm_engine_publickey.md | 26 ++ olvm/docs/provision_vnc.md | 28 +++ olvm/docs/requirements.md | 26 ++ olvm/docs/templates/answer_file.j2.md | 24 ++ .../templates/egress_security_rules.j2.md | 25 ++ olvm/docs/templates/etc_hosts_kvm.j2.md | 24 ++ .../templates/ingress_security_rules.j2.md | 25 ++ olvm/docs/templates/oci_vars.j2.md | 26 ++ olvm/docs/terminate_instance.md | 27 +++ 134 files changed, 5315 insertions(+) create mode 100644 labs/docs/README.md create mode 100644 labs/docs/olam-hello-world.md create mode 100644 ocne/docs/README copy.md create mode 100644 ocne/docs/README.md create mode 100644 ocne/docs/build.md create mode 100644 ocne/docs/ceph_deployments.md create mode 100644 ocne/docs/create_fss.md create mode 100644 ocne/docs/create_instance.md create mode 100644 ocne/docs/create_lb.md create mode 100644 ocne/docs/create_ocir.md create mode 100644 ocne/docs/create_vlan.md create mode 100644 ocne/docs/default_vars.md create mode 100644 ocne/docs/delete_fss.md create mode 100644 ocne/docs/delete_lb.md create mode 100644 ocne/docs/delete_ocir.md create mode 100644 ocne/docs/deploy_ocne_compact.md create mode 100644 ocne/docs/deploy_ocne_full.md create mode 100644 ocne/docs/deploy_ocne_none.md create mode 100644 ocne/docs/deploy_ocne_quick.md create mode 100644 ocne/docs/deploy_ocne_vlan.md create mode 100644 ocne/docs/fss_deployments.md create mode 100644 ocne/docs/host_assign_vlan_ip.md create mode 100644 ocne/docs/host_setup.md create mode 100644 ocne/docs/ol8_repo_config.md create mode 100644 ocne/docs/ol9_repo_config.md create mode 100644 ocne/docs/preconfig_oci_ccm.md create mode 100644 ocne/docs/provision_istio.md create mode 100644 ocne/docs/provision_kubectl.md create mode 100644 ocne/docs/provision_oci_ccm.md create mode 100644 ocne/docs/provision_ocne.md create mode 100644 ocne/docs/pvc.j2.md create mode 100644 ocne/docs/templates/cluster.j2.md create mode 100644 ocne/docs/templates/egress_security_rules.j2.md create mode 100644 ocne/docs/templates/filesystem.j2.md create mode 100644 ocne/docs/templates/fss_pod.j2.md create mode 100644 ocne/docs/templates/fss_pv.j2.md create mode 100644 ocne/docs/templates/fss_pvc.j2.md create mode 100644 ocne/docs/templates/fss_vars.j2.md create mode 100644 ocne/docs/templates/ingress_security_rules.j2.md create mode 100644 ocne/docs/templates/istio_lb.j2.md create mode 100644 ocne/docs/templates/lb_vars.j2.md create mode 100644 ocne/docs/templates/myenvironment.j2.md create mode 100644 ocne/docs/templates/oci_vars.j2.md create mode 100644 ocne/docs/templates/ocir_vars.j2.md create mode 100644 ocne/docs/templates/storageclass.j2.md create mode 100644 ocne/docs/templates/toolbox.j2.md create mode 100644 ocne/docs/templates/vm.j2.md create mode 100644 ol/docs/README.md create mode 100644 ol/docs/block.md create mode 100644 ol/docs/build.md create mode 100644 ol/docs/create_instance.md create mode 100644 ol/docs/default_vars.md create mode 100644 ol/docs/download_ol_iso.md create mode 100644 ol/docs/host_setup.md create mode 100644 ol/docs/passwordless_setup.md create mode 100644 ol/docs/provision_kvm.md create mode 100644 ol/docs/provision_kvm_vm.md create mode 100644 ol/docs/provision_podman.md create mode 100644 ol/docs/provision_vbox.md create mode 100644 ol/docs/provision_vnc.md create mode 100644 ol/docs/requirements.md create mode 100644 ol/docs/templates/egress_security_rules.j2.md create mode 100644 ol/docs/templates/ingress_security_rules.j2.md create mode 100644 ol/docs/templates/oci_vars.j2.md create mode 100644 ol/docs/templates/vm_template.j2.md create mode 100644 ol/docs/update_all_rpms.md create mode 100644 olam/docs/README.md create mode 100644 olam/docs/block.md create mode 100644 olam/docs/build.md create mode 100644 olam/docs/check_instance_available.md create mode 100644 olam/docs/configure_passwordless_ssh.md create mode 100644 olam/docs/convert_ansible_inventory.sh.md create mode 100644 olam/docs/create_instance.md create mode 100644 olam/docs/default_vars.md create mode 100644 olam/docs/deploy_olam_cluster.md create mode 100644 olam/docs/deploy_olam_none.md create mode 100644 olam/docs/deploy_olam_olae.md create mode 100644 olam/docs/deploy_olam_single.md create mode 100644 olam/docs/deploy_olam_v1.md create mode 100644 olam/docs/get_facts.md create mode 100644 olam/docs/provision_builder.md create mode 100644 olam/docs/provision_free_ipa.md create mode 100644 olam/docs/provision_git_server.md create mode 100644 olam/docs/provision_instance_basics.md create mode 100644 olam/docs/provision_kvm.md create mode 100644 olam/docs/provision_pah.md create mode 100644 olam/docs/provision_vnc.md create mode 100644 olam/docs/requirements.md create mode 100644 olam/docs/templates/bindep.txt.j2.md create mode 100644 olam/docs/templates/egress_security_rules.j2.md create mode 100644 olam/docs/templates/execution_environment.yml.j2.md create mode 100644 olam/docs/templates/hosts.j2.md create mode 100644 olam/docs/templates/ingress_security_rules.j2.md create mode 100644 olam/docs/templates/install_ipa.j2.md create mode 100644 olam/docs/templates/nginx.conf.j2.md create mode 100644 olam/docs/templates/nginx.conf_v1.j2.md create mode 100644 olam/docs/templates/oci_vars.j2.md create mode 100644 olam/docs/templates/playbook.yml.j2.md create mode 100644 olam/docs/templates/receptor.conf.j2.md create mode 100644 olam/docs/templates/receptor_cluster.conf.j2.md create mode 100644 olam/docs/templates/requirements.txt.j2.md create mode 100644 olam/docs/templates/requirements.yml.j2.md create mode 100644 olam/docs/terminate_instance.md create mode 100644 olam/docs/update_all_rpms.md create mode 100644 olvm/docs/README.md create mode 100644 olvm/docs/build.md create mode 100644 olvm/docs/check_instance_available.md create mode 100644 olvm/docs/configure_passwordless_ssh.md create mode 100644 olvm/docs/configure_secondary_nic.md create mode 100644 olvm/docs/create_block_storage.md create mode 100644 olvm/docs/create_hostfile_secondary_nic.md create mode 100644 olvm/docs/create_instance.md create mode 100644 olvm/docs/create_vlan.md create mode 100644 olvm/docs/default_vars.md create mode 100644 olvm/docs/ovirt_add_hosts.md create mode 100644 olvm/docs/ovirt_add_logical_network.md create mode 100644 olvm/docs/ovirt_add_storage_domain.md create mode 100644 olvm/docs/ovirt_check_hosts.md create mode 100644 olvm/docs/ovirt_connection_test.md create mode 100644 olvm/docs/ovirt_create_vm_from_template.md create mode 100644 olvm/docs/ovirt_delete_host.md create mode 100644 olvm/docs/ovirt_import_template.md create mode 100644 olvm/docs/ovirt_list_hosts.md create mode 100644 olvm/docs/provision_instance_basics.md create mode 100644 olvm/docs/provision_olvm_engine.md create mode 100644 olvm/docs/provision_olvm_engine_publickey.md create mode 100644 olvm/docs/provision_vnc.md create mode 100644 olvm/docs/requirements.md create mode 100644 olvm/docs/templates/answer_file.j2.md create mode 100644 olvm/docs/templates/egress_security_rules.j2.md create mode 100644 olvm/docs/templates/etc_hosts_kvm.j2.md create mode 100644 olvm/docs/templates/ingress_security_rules.j2.md create mode 100644 olvm/docs/templates/oci_vars.j2.md create mode 100644 olvm/docs/terminate_instance.md diff --git a/labs/docs/README.md b/labs/docs/README.md new file mode 100644 index 0000000..0a1ca73 --- /dev/null +++ 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 new file mode 100644 index 0000000..823cc6b --- /dev/null +++ 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 copy.md b/ocne/docs/README copy.md new file mode 100644 index 0000000..4da2639 --- /dev/null +++ b/ocne/docs/README copy.md @@ -0,0 +1,228 @@ +# OCNE Automation Reference Documentation + +## 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 + +- [OCNE Automation Reference Documentation](#ocne-automation-reference-documentation) + - [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 | Launches OCI VM instances, networks, attaches storage and VNICs. | - | +| ceph_deployments.yml | 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 | 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 | 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 | Provisions OCI LB, configures health checks, backend set, exports LB IP to vars. | lb_vars.j2 | +| create_ocir.yml | Provisions OCI Container Registry and writes config for image integration. | ocir_vars.j2 | +| create_vlan.yml | Provisions VLAN in OCI/VCN and sets associated security groups. | - | +| default_vars.yml | Defines default topology, sizing, and feature toggles. | - | +| delete_fss.yml / delete_lb.yml / delete_ocir.yml | Teardown/removes FSS, Load Balancer, and Registry resources from OCI. | - | +| deploy_ocne_* | Orchestrate full OCNE cluster install (compact/full/quick/vlan/none). | myenvironment.j2 (in some flows) | +| fss_deployments.yml | 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 | Assigns static VLAN IPs and builds SSH trust for all nodes. | - | +| host_setup.yml | Sets up users, keys, directories, and enables passwordless SSH for automation. | - | +| ol8_repo_config.yml / ol9_repo_config.yml | Enables/disables YUM repos for OL8/OL9 and OLCNE install/update. | - | +| preconfig_oci_ccm.yml | Sets OCI CCM env variables in .bashrc for controller/cluster manager integration. | - | +| provision_istio.yml | Deploys Istio mesh module, renders and applies custom LB setup. | istio_lb.j2 | +| provision_kubectl.yml | Gives cluster users non-root access to kubectl, copying and exporting config. | - | +| provision_oci_ccm.yml | Deploys Oracle CCM for dynamic LB/service and cloud integration. | oci_vars.j2 | +| provision_ocne.yml | Manual path for full cluster install with conditional logic and config export. | myenvironment.j2 | + +--- + +## Jinja2 Templates + +| Template | Purpose / Usage | +| ------------------------- | ------------------------------------------------------------- | +| cluster.j2 | CephCluster CR (Rook/Ceph storage) | +| filesystem.j2 | CephFilesystem CR (CephFS persistence) | +| toolbox.j2 | Rook Ceph toolbox pod/deployment for CLI ops/troubleshooting | +| vm.j2 | KubeVirt VM manifest (K8s + OCI image + CephFS + cloud-init) | +| storageclass.j2 | StorageClass for dynamic CephFS PV provisioning (rook-cephfs) | +| pvc.j2 / fss_pvc.j2 | PVCs for CephFS (dynamic/static provisioning flows) | +| fss_pv.j2 | Static PersistentVolume for OCI FSS via CSI | +| fss_pod.j2 | Test/demo pod mounting the above PVC | +| fss_vars.j2 / oci_vars.j2 / lb_vars.j2 / ocir_vars.j2 | Dynamic YAML config/vars generated by playbooks | +| ingress_security_rules.j2 / egress_security_rules.j2 | Vars for security list rules in OCI, rendered by automation | +| istio_lb.j2 | OCI LB (internal, flex) setup for Istio Gateway | +| myenvironment.j2 | Master configuration file for `olcnectl` environment/module creation | + +--- + +## Tree Listing + +```markdown +|── ocne +    ├── build.md +    ├── ceph_deployments.md +    ├── create_fss.md +    ├── create_instance.md +    ├── create_lb.md +    ├── create_ocir.md +    ├── create_vlan.md +    ├── default_vars.md +    ├── delete_fss.md +    ├── delete_lb.md +    ├── delete_ocir.md +    ├── deploy_ocne_compact.md +    ├── deploy_ocne_full.md +    ├── deploy_ocne_none.md +    ├── deploy_ocne_quick.md +    ├── deploy_ocne_vlan.md +    ├── fss_deployments.md +    ├── host_assign_vlan_ip.md +    ├── host_setup.md +    ├── ol8_repo_config.md +    ├── ol9_repo_config.md +    ├── preconfig_oci_ccm.md +    ├── provision_istio.md +    ├── provision_kubectl.md +    ├── provision_oci_ccm.md +    ├── provision_ocne.md +    ├── pvc.j2.md +    ├── README copy.md +    ├── README.md +    └── templates +    ├── cluster.j2.md +    ├── egress_security_rules.j2.md +    ├── filesystem.j2.md +    ├── fss_pod.j2.md +    ├── fss_pv.j2.md +    ├── fss_pvc.j2.md +    ├── fss_vars.j2.md +    ├── ingress_security_rules.j2.md +    ├── istio_lb.j2.md +    ├── lb_vars.j2.md +    ├── myenvironment.j2.md +    ├── oci_vars.j2.md +    ├── ocir_vars.j2.md +    ├── storageclass.j2.md +    ├── toolbox.j2.md +    └── vm.j2.md +``` + +--- + +## 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/README.md b/ocne/docs/README.md new file mode 100644 index 0000000..880237e --- /dev/null +++ b/ocne/docs/README.md @@ -0,0 +1,3 @@ +# README.md + + diff --git a/ocne/docs/build.md b/ocne/docs/build.md new file mode 100644 index 0000000..051f0c4 --- /dev/null +++ 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" diff --git a/ocne/docs/ceph_deployments.md b/ocne/docs/ceph_deployments.md new file mode 100644 index 0000000..fc7473e --- /dev/null +++ b/ocne/docs/ceph_deployments.md @@ -0,0 +1,45 @@ +# ceph_deployments.yml Documentation + +## Purpose & Overview + +Deploys a suite of Ceph and Kubernetes configuration files to all control plane nodes in the cluster. It renders key Jinja2 templates into YAML manifests for storage, virtualization, and cluster configuration needed for a Ceph-backed Kubernetes environment. + +## When to Use + +Run this playbook after control plane nodes are provisioned but before initial cluster storage, toolbox, and compute workloads are deployed. It ensures all supporting manifests are available in each control plane host's home directory. + +## Key Variables & Inputs + +- `username`: The user under which the configs will be written. +- `groups['controlplane']`: Inventory group of target nodes. +- No other required variables; customization is generally achieved by editing referenced Jinja2 templates. + +## Task Breakdown + +For each control plane node, the playbook: + +- Renders and distributes the following configuration files using Ansible's template module: + - **cluster.yaml**: From cluster.j2, defines the Ceph Cluster. + - **toolbox.yaml**: From toolbox.j2, administrative pod configuration for Ceph management. + - **filesystem.yaml**: From filesystem.j2, CephFileSystem resource definition. + - **storageclass.yaml**: From storageclass.j2, K8s StorageClass for Ceph-backed storage. + - **pvc.yaml**: From pvc.j2, K8s PersistentVolumeClaim for dynamic storage. + - **vm.yaml**: From vm.j2, sample virtual machine resource. +- Each file is created in `~/` of the delegated node with mode 0644 and correct ownership. +- Uses `become` for privilege escalation as needed. + +## Dependencies & Relationships + +- **Templates Used:** cluster.j2, toolbox.j2, filesystem.j2, storageclass.j2, pvc.j2, vm.j2 (all in ocne/templates/). +- **Runs on:** Every host in the Ansible inventory group `controlplane`; user defined by `username` variable. +- Typically invoked after the infrastructure is deployed (e.g., after build.yml). + +## Output/Result + +- Each control plane node receives a full set of Ceph and K8s manifest YAMLs needed for further deployment and management. +- These files enable the subsequent setup and orchestration of persistent, Ceph-backed Kubernetes storage services. + +## Example Run + +```bash +ansible-playbook ceph_deployments.yml -e "username=opc" diff --git a/ocne/docs/create_fss.md b/ocne/docs/create_fss.md new file mode 100644 index 0000000..dc50b28 --- /dev/null +++ b/ocne/docs/create_fss.md @@ -0,0 +1,48 @@ +# create_fss.yml Documentation + +## Purpose & Overview + +Automates the end-to-end setup of Oracle Cloud Infrastructure (OCI) File Storage Service (FSS) for cluster or NFS use. This playbook provisions mount targets, discovers required IDs and IPs, creates a backing file system, sets up an export path, and documents discovered connection parameters for subsequent workloads. + +## When to Use + +Use this playbook when: + +- A shared network file system is required for OCI-based Kubernetes, Oracle Linux, or other distributed workloads. +- You want to ensure all FSS resources (mount target, file system, and export) are provisioned and recorded in one step. + +## Key Variables & Inputs + +- `my_availability_domain`: OCI AD for FSS resources. +- `my_compartment_id`: OCI compartment OCID. +- `my_subnet_id`: Subnet OCID for the mount target. +- `debug_enabled`: Enables step-by-step output for monitoring or troubleshooting. + +## Task Breakdown + +- **Provision FSS Mount Target:** Creates a mount target using `oci_file_storage_mount_target`. +- **Debug Output:** Optionally prints results. +- **Set Facts:** Extracts mount target, export set, and private IP IDs. +- **Private IP Lookup:** Retrieves mount target primary IP address. +- **Provision FSS File System:** Creates a file system for storage. +- **Export Creation:** Sets up a file system export making `/fss-ocne` accessible to cluster nodes. +- **Set/Write FSS Vars:** Records all generated/assigned values in a vars file via templating (`fss_vars.j2`). + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: `oci_file_storage_mount_target`, `oci_file_storage_file_system`, `oci_file_storage_export`, and network/private IP modules. +- Relies on variables produced here for matching mount operations in subsequent playbooks. +- Uses the templated file `fss_vars.j2` for writing generated connection values. + +## Output/Result + +- A mounted, exported, addressable OCI File Storage resource. +- `fss_vars.yml` containing all IDs, IPs, and paths required by following steps. + +## Example Run + +```bash +ansible-playbook create_fss.yml \ + -e "my_compartment_id=..." \ + -e "my_availability_domain=..." \ + -e "my_subnet_id=..." diff --git a/ocne/docs/create_instance.md b/ocne/docs/create_instance.md new file mode 100644 index 0000000..840163f --- /dev/null +++ b/ocne/docs/create_instance.md @@ -0,0 +1,70 @@ +# create_instance.yml Documentation + +## Purpose & Overview + +Orchestrates the end-to-end setup, configuration, and teardown of a complete Oracle Linux and Kubernetes test environment on Oracle Cloud Infrastructure (OCI). This master playbook provisions all key resources: network (VCN, subnets, security lists), compute instances (operator, control plane, worker nodes), file storage, load balancer, and OCI registry. It supports lifecycle operations from initial build to cleanup. + +## When to Use + +Use this playbook to stand up or tear down a full stack for cloud-native/Oracle CNE testing or training on OCI, especially when you need an automated, parameterized, and fully documented workflow covering all infra as code. + +## Key Variables & Inputs + +- Major variables include (but are not limited to): + - `ad_placement`: Placement index for OCI Availability Domains + - `compartment_id`, `compartment_name`: The target OCI compartment(s) + - `os`, `os_version`, `instance_shape`, `instance_ocpus`, `instance_memory`: Image and sizing details + - `private_key`: SSH private key + - `use_vlan`, `use_fss`, `use_lb`, `use_ocir`: Feature toggles + - Inventory and cluster node definition via `compute_instances` + - Many variables sourced from imported files: `default_vars.yml`, `oci_vars.yml`, `lb_vars.yml`, etc. + - Extra-vars can be supplied at runtime to override defaults + +## Task Breakdown + +1. **Network Setup:** + - Creates VCN, subnets, IGW, route tables, security lists, and configures rules (via Jinja2-ingressed templates). +2. **Image Lookup:** + - Locates and caches latest Oracle Linux image matching parameters. +3. **Instance Provisioning:** + - Builds operator, control, and worker nodes via included build.yml, using looped variables for flexible topologies. +4. **Storage & Load Balancing (Conditional):** + - Invokes playbooks for FSS (create_fss.yml), LB (create_lb.yml), and OCIR (create_ocir.yml) when enabled. +5. **Cluster Installation:** + - Runs host config (host_setup.yml), IP/VLAN assignment, and then launches main platform install (via deploy_ocne_*.yml). +6. **Reporting:** + - Shows host inventory, addresses, and registry information for later use. +7. **Teardown:** + - Optionally runs deletion playbooks for all resources, including cloud infra and local artifacts. + +## Dependencies & Relationships + +- **Imports/Includes:** + - Includes and relies on logic/outputs from: build.yml, create_fss.yml, create_lb.yml, create_ocir.yml, delete_fss.yml, delete_lb.yml, delete_ocir.yml, deploy_ocne_*.yml, and Jinja2 templates for security rules/vars. +- **Module Requirements:** + - OCI Ansible Collection (compute, network, load balancer, file storage, identity modules, etc.) +- **Artifacts:** + - Writes config and generated vars files (oci_vars.yml, lb_vars.yml, fss_vars.yml) + +## Output/Result + +- A complete, ready-to-use OCI test or demo environment +- Inventory of public/private IPs, registry and storage info +- Ability to destroy and clean up all cloud resources in a controlled way + +## Example Run + +```bash +ansible-playbook create_instance.yml \ + -e "compartment_id=..." \ + -e "use_vlan=true" \ + -e "use_fss=true" \ + -e "use_lb=true" \ + -e "use_ocir=true" +``` + +## Teardown Example + +```bash +ansible-playbook create_instance.yml --tags "teardown" \ + -e "compartment_id=..." diff --git a/ocne/docs/create_lb.md b/ocne/docs/create_lb.md new file mode 100644 index 0000000..f32781c --- /dev/null +++ b/ocne/docs/create_lb.md @@ -0,0 +1,48 @@ +# create_lb.yml Documentation + +## Purpose & Overview + +Automates provisioning and configuration of a private load balancer on Oracle Cloud Infrastructure (OCI), intended to provide front-end access (port 6443/TCP) to a dynamic pool of Kubernetes control plane nodes. The playbook registers backends, configures health checks, and sets appropriate facts for use by downstream tasks and users. + +## When to Use + +Use this playbook when: + +- Deploying a highly available Kubernetes or Oracle Linux cluster in OCI. +- You want to automate the deployment of an OCI load balancer, backend registration, and config recording for subsequent steps or documentation. + +## Key Variables & Inputs + +- `my_compartment_id`: OCI compartment OCID. +- `my_subnet_id`: Target subnet for the load balancer. +- `groups['controlplane']`: Determines which hosts become load balancer backends. +- `empty_cp_nodes`: Used to optionally filter out empty/missing control planes (integer count). +- `debug_enabled`: Turns stepwise debug prints on/off. + +## Task Breakdown + +- **LB Provisioning:** Creates a private load balancer via `oci_loadbalancer_load_balancer`. +- **Backend Set & Listener:** Creates backend set with TCP/6443 health checks and a listener using `oci_loadbalancer_backend_set` and `oci_loadbalancer_listener`. +- **Control Plane Targeting:** Dynamically discovers real control plane nodes for backend pool registration. +- **Backend Registration:** Adds each control plane host to the load balancer on required port. +- **Config Export:** Writes connection details to `lb_vars.yml` for later consumption using Jinja2 template. +- **Debug Output:** Optionally prints all relevant addresses and state details for review. + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: load balancer modules, backend set/listener management. +- Uses data and facts from create_instance.yml and related playbooks. +- **Templates Used:** lb_vars.j2 for writing finalized variables. +- Interacts with all hosts in `controlplane` group and expects facts/addresses to be set correctly by prior steps. + +## Output/Result + +- A private OCI load balancer with health-checked K8s API backends. +- Updated configuration file `lb_vars.yml` reflecting endpoints and credentials for next-stage tasks. + +## Example Run + +```bash +ansible-playbook create_lb.yml \ + -e "my_compartment_id=..." \ + -e "my_subnet_id=..." diff --git a/ocne/docs/create_ocir.md b/ocne/docs/create_ocir.md new file mode 100644 index 0000000..bd66baa --- /dev/null +++ b/ocne/docs/create_ocir.md @@ -0,0 +1,42 @@ +# create_ocir.yml Documentation + +## Purpose & Overview + +Automates the creation of a private OCI Container Registry (OCIR) repository for secure Docker image storage and deployment. The playbook provisions a repository, fetches/exposes its key identifiers (ID, name, namespace), and writes them to a structured variable file for downstream use. + +## When to Use + +Use this playbook when: + +- You need a private Docker image repository to support custom container builds, CI/CD, or image pulls within your Oracle Linux or Kubernetes lab environments. +- Integrating custom applications or distributing lab images in a test or production cluster. + +## Key Variables & Inputs + +- `my_compartment_id`: OCI compartment OCID. +- `debug_enabled`: Enables stepwise output and debugging information. + +## Task Breakdown + +- **Repository Provisioning:** Creates a container repo named `demo/oraclelinux-cloud` (private by default) in the specified compartment. +- **Debug Output (Optional):** Prints resulting repo details when enabled. +- **Fact/Var Collection:** Gathers the OCIR repo's unique ID, name, and namespace for cluster authentication. +- **Config Export:** Writes all retrieved registry information (~ocir_vars.yml) for consumption by further configuration or install steps. + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: `oci_artifacts_container_repository`. +- Relies on variables for compartment selection. +- **Templates Used:** ocir_vars.j2 for output variables file. +- Used as part of create_instance.yml deployment or as a standalone prereq for enabling private registry features. + +## Output/Result + +- New OCIR repository suitable for private Docker image hosting. +- Variable file `ocir_vars.yml` that supplies registry information for consumption by other playbooks or user tooling. + +## Example Run + +```bash +ansible-playbook create_ocir.yml \ + -e "my_compartment_id=..." diff --git a/ocne/docs/create_vlan.md b/ocne/docs/create_vlan.md new file mode 100644 index 0000000..374835a --- /dev/null +++ b/ocne/docs/create_vlan.md @@ -0,0 +1,47 @@ +# create_vlan.yml Documentation + +## Purpose & Overview + +Automates the creation of a VLAN in Oracle Cloud Infrastructure (OCI), configuring it within a target Virtual Cloud Network (VCN) and compartment, and applying a dedicated Network Security Group (NSG) with suitable ingress/egress rules. + +## When to Use + +Use this playbook when: + +- VLAN-based isolation is needed for cluster resources or workloads within a Linux/Kubernetes OCI deployment. +- You want reproducible, API-driven setup of VLAN and its network security. + +## Key Variables & Inputs + +- `my_availability_domain`: OCI AD for the VLAN. +- `vlan_cidr_block`: Address range for the VLAN. +- `my_compartment_id`: OCI compartment OCID. +- `my_vcn_id`: The ID of the Virtual Cloud Network for VLAN/NSG association. +- `debug_enabled`: Enables detailed debug information if set. + +## Task Breakdown + +- **Create Network Security Group:** Using `oci_network_security_group`, provisions a new NSG scoped to the VLAN's VCN and compartment. +- **Set NSG Rules:** Adds both egress (all traffic to 0.0.0.0/0) and ingress (all from VCN CIDR) rules to the NSG via `oci_network_security_group_security_rule_actions`. +- **VLAN Creation:** Allocates the VLAN resource within the OCI AD, VCN, and compartment, attaching the new NSG. +- **Fact Propagation:** Stores IDs for chaining to future playbooks/actions. +- **Debug Output:** Optionally prints resultant VLAN and NSG state. + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: NSG and VLAN modules. +- Relies on previously created VCN (from create_instance.yml), correct compartment/AD configuration, and optionally interacts with other network playbooks for further setup. + +## Output/Result + +- A new VLAN resource in OCI, with dedicated network security group and rules. +- Exposed variables (`my_vlan_id`, `my_nsg_id`) for use in provisioning compute instances, load balancers, etc. + +## Example Run + +```bash +ansible-playbook create_vlan.yml \ + -e "my_compartment_id=..." \ + -e "my_availability_domain=..." \ + -e "my_vcn_id=..." \ + -e "vlan_cidr_block=10.0.1.0/24" diff --git a/ocne/docs/default_vars.md b/ocne/docs/default_vars.md new file mode 100644 index 0000000..1fb24ad --- /dev/null +++ b/ocne/docs/default_vars.md @@ -0,0 +1,59 @@ +# default_vars.yml Documentation + +## Purpose & Overview + +Defines the default variables for all principal Ansible playbooks in the Oracle Cloud Native Environment (Oracle CNE) automation suite. Controls environment topology (instances, types, count), hardware sizing, options for enabling/disabling cloud features, debug toggles, and distribution settings. + +## When to Use + +- Included (via `vars_files`) by most playbooks to provide sane defaults for user convenience and repeatability. +- Edit as needed to adjust the size, features, or composition of your OCI-based Kubernetes/Oracle Linux cluster. + +## Variables and Their Purposes + +### Cluster Topology & Sizing + +- **compute_instances**: Maps each node to a role (operator/controlplane/worker) and name. +- **os, os_version**: Linux flavor and version for instance provisioning. +- **instance_shape, instance_ocpus, instance_memory**: OCI instance shape, CPU, and RAM used for new VMs. +- **subnet_cidr_block**: The CIDR block assigned by default to the subnet for the cluster. + +### VLAN & Networking Options + +- **use_vlan**: Boolean toggle for VLAN provisioning and assignment. +- **vlan_cidr_block**: CIDR block for VLAN address space if enabled. + +### User & Debug Options + +- **username**: Target SSH/OS-level username for setup. +- **user_default_password**: Default password if user accounts require setting. +- **debug_enabled**: Enable verbose debug info and Ansible outputs. + +### Oracle CNE/Cluster Type + +- **ocne_type**: Controls which Oracle CNE deployment mode is used (quick/full/none). +- **use_ocne_full, use_vlan_full**: Additional toggles for full deployments or VLAN-everywhere. + +### Optional Features + +- **use_lb, use_int_lb, use_ingress_lb**: Enable/disable load balancer resources. +- **oci_ccm_bash, use_oci_ccm, use_istio**: CCM and Istio integration toggles. +- **use_fss**: Enable/disable Oracle File Storage Service provisioning. +- **add_ceph_block_storage, ceph_volume_size_in_gbs**: Enable/parametrize Ceph block storage creation. +- **add_ceph_deployments**: Enable Ceph configuration templating. +- **use_ocir**: Toggle for registry support. + +### Oracle Linux Repos (for K8s/OLCNE) + +- **ol8_enable_repo, ol8_disable_repo, ol9_enable_repo, ol9_disable_repo**: Names of Oracle Linux YUM repositories to enable/disable based on OS version. + +### Advanced/Placeholder Vars + +- **empty_cp_nodes, empty_wrk_nodes**: Used to modify/control pool sizing or test empty/edge cases. + +## How to Customize + +Edit this file before your run, or override its values at runtime with Ansible `-e` extra-vars: + +```bash +ansible-playbook create_instance.yml -e "instance_memory=64 use_lb=true" diff --git a/ocne/docs/delete_fss.md b/ocne/docs/delete_fss.md new file mode 100644 index 0000000..e9c1bc9 --- /dev/null +++ b/ocne/docs/delete_fss.md @@ -0,0 +1,43 @@ +# delete_fss.yml Documentation + +## Purpose & Overview + +Destroys File Storage Service (FSS) resources in Oracle Cloud Infrastructure (OCI) that were previously provisioned for the cluster or NFS workloads. The playbook ensures that all components—export path, mount target, and file system—are deleted safely and in correct dependency order. + +## When to Use + +Run this playbook when: + +- Tearing down or resetting the OCI lab/test/development environment. +- Decommissioning infrastructure after automation testing to prevent resource leakage and avoid charges. + +## Key Variables & Inputs + +- `export_id`: The ID of the FSS export path to delete. +- `mount_target_id`: The ID of the mount target to remove. +- `file_system_id`: The ID of the backing file system to delete. + +## Task Breakdown + +- **Export Deletion:** Deletes the FSS export—removes the exported file system access path. +- **Mount Target Deletion:** Deletes the FSS mount target object from the given subnet. +- **File System Deletion:** Destroys the actual persistent file storage volume. + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: file storage modules. +- The identified IDs must be present (generally gathered from create_fss.yml/fss_vars.yml). +- Called as part of broad teardown (e.g., from create_instance.yml's cleanup/teardown phase). + +## Output/Result + +- All referenced FSS resources deleted and cleaned from OCI compartment. +- No file system artifacts, orphaned mounts, or cloud storage bills. + +## Example Run + +```bash +ansible-playbook delete_fss.yml \ + -e "export_id=ocid1.export.oc1..." \ + -e "mount_target_id=ocid1.mounttarget.oc1..." \ + -e "file_system_id=ocid1.filesystem.oc1..." diff --git a/ocne/docs/delete_lb.md b/ocne/docs/delete_lb.md new file mode 100644 index 0000000..75252e5 --- /dev/null +++ b/ocne/docs/delete_lb.md @@ -0,0 +1,37 @@ +# delete_lb.yml Documentation + +## Purpose & Overview + +Deletes a private load balancer previously created in Oracle Cloud Infrastructure (OCI) by this automation suite. Ensures cloud resources are freed and incurs no further charges. + +## When to Use + +Run this playbook when: + +- You wish to clean up or decommission lab, test, or demo infrastructure. +- As part of a full cluster/application teardown. + +## Key Variables & Inputs + +- `private_load_balancer_id`: The unique ID (OCID) of the load balancer to delete. Typically provided as a fact/var from create_lb.yml outputs. + +## Task Breakdown + +- **Load Balancer Deletion:** Removes the targeted load balancer using `oci_loadbalancer_load_balancer` with state 'absent'. + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: load balancer resources. +- Generally called automatically from cleanup logic in create_instance.yml, or can be run stand-alone. +- Needs fact/variable population from previous provisioning plays. + +## Output/Result + +- Targeted load balancer is deleted from OCI. +- Resources and billing related to this load balancer cease. + +## Example Run + +```bash +ansible-playbook delete_lb.yml \ + -e "private_load_balancer_id=ocid1.loadbalancer.oc1..." diff --git a/ocne/docs/delete_ocir.md b/ocne/docs/delete_ocir.md new file mode 100644 index 0000000..03e4afc --- /dev/null +++ b/ocne/docs/delete_ocir.md @@ -0,0 +1,36 @@ +# delete_ocir.yml Documentation + +## Purpose & Overview + +Removes a private OCI Container Registry (OCIR) repository previously provisioned for the cluster or workloads. This ensures that the registry and all images within are deleted, eliminating storage costs and resource remnants. + +## When to Use + +Run this playbook when: + +- Cleaning up cloud resources after a demonstration, workshop, or test. +- Deleting an obsolete or transient OCI Container Registry. + +## Key Variables & Inputs + +- `ocir_id`: The unique OCID of the container repository to delete, set by create_ocir.yml. + +## Task Breakdown + +- **Repository Deletion:** Uses `oci_artifacts_container_repository` to delete the identified registry repository. + +## Dependencies & Relationships + +- Requires Oracle OCI Ansible Collection: artifacts/container modules. +- Intended for use after create_ocir.yml or as part of the teardown phase in create_instance.yml. +- Requires accurate variable passing for repository OCID. + +## Output/Result + +- Complete deletion of the targeted OCIR, including all contained images. +- No further storage or billing attached to this registry. + +## Example Run + +```bash +ansible-playbook delete_ocir.yml -e "ocir_id=ocid1.containerrepo.oc1..xxxx" diff --git a/ocne/docs/deploy_ocne_compact.md b/ocne/docs/deploy_ocne_compact.md new file mode 100644 index 0000000..7bbe225 --- /dev/null +++ b/ocne/docs/deploy_ocne_compact.md @@ -0,0 +1,49 @@ +# deploy_ocne_compact.yml Documentation + +## Purpose & Overview +Prepares the operator node for an Oracle Cloud Native Environment (Oracle CNE) compact deployment in OCI. Handles OS-level prerequisites, configures Oracle CNE repositories, networking, time sync, disables swap, adds kernel and firewall requirements, installs required Oracle CNE components, bootstraps security certificates, and launches Oracle CNE control-plane services. + +## When to Use + +Use this playbook: + +- As the first step for deploying a single-node (operator-based) Oracle CNE/Kubernetes. +- To set up a working Oracle CNE control plane in a minimal or lab installation scenario. + +## Key Variables & Inputs + +- `ocne_registry_location`: Container registry for Oracle CNE images. +- `control_plane_nodes`: Comma-separated list of operator hostnames. +- `username`: OS user for privileged actions (from default_vars.yml). +- Other environment/host variables as from included default_vars.yml + +## Task Breakdown + +- **Show Nodes/Debug:** Optionally prints target node list. +- **Configure Repositories:** Sets up Oracle CNE YUM repos for OL8 or OL9. +- **Install Chrony:** Installs and enables Chrony for time synchronization. +- **Disable Swap:** Disables swap both immediately and in /etc/fstab. +- **Configure Firewall:** Opens required TCP/UDP ports for Oracle CNE/cluster operation. +- **Add Firewall Interface:** Adds trusted CNI interface for container networking. +- **Kernel Modules:** Loads and persists required kernel modules. +- **Install OLCNE Packages:** Installs main Oracle CNE tools and agents. +- **User/Group Setup:** Adds the operator user to the `olcne` group and resets SSH connections. +- **Service Setup:** Manages Oracle CNE API server and agent services. +- **Certificate Management:** Generates, distributes, and installs required X.509 certificates using `olcnectl`. +- **Bootstrap Services:** Starts Oracle CNE API server and agent with required arguments and keys. + +## Dependencies & Relationships + +- Used after network and compute provisioning is done (see create_instance.yml). +- Invokes other task files (ol8_repo_config.yml, ol9_repo_config.yml). +- Strongly coupled with operator node details as provisioned earlier. +- Oracle CNE repo setup and `olcnectl` must be available on the target host. + +## Output/Result + +- An operator node with all requisite packages, services, security artifacts, and configurations to serve as Oracle CNE/K8s control plane (or standalone node). + +## Example Run + +```bash +ansible-playbook deploy_ocne_compact.yml --limit operator diff --git a/ocne/docs/deploy_ocne_full.md b/ocne/docs/deploy_ocne_full.md new file mode 100644 index 0000000..85bb018 --- /dev/null +++ b/ocne/docs/deploy_ocne_full.md @@ -0,0 +1,48 @@ +# deploy_ocne_full.yml Documentation + +## Purpose & Overview + +Prepares and deploys a complete, multi-node Oracle Cloud Native Environment (Oracle CNE) cluster spanning operator, control plane, and worker hosts. Automates system prep (SELinux, OS config, networking), time sync, repo setup, swap disablement, core package installation, firewall/kernel setup, Oracle CNE agent/api-server enablement, and certificate management, followed by orchestrating the full Oracle CNE install (platform CLI, ccm, Istio, storage, etc). + +## When to Use + +Use this playbook: + +- When deploying a production-like or well-segmented Oracle CNE Kubernetes environment with Operator, Control-Plane, and Worker nodes on OCI. +- For lab/testing where a realistic, full-topology configuration is required. + +## Key Variables & Inputs + +- Host group memberships: `operator`, `controlplane`, `worker` +- Environment vars and toggles in `default_vars.yml`, `oci_vars.yml` +- `ocne_registry_location`: Container registry with Oracle CNE images. +- Fact variables passed from previous provisioning (IDs, domains, feature toggles). + +## Task Breakdown + +- **System Pre-Install:** SELinux config for iptables, repo configuration (OL8/OL9), Chrony installation, swap disablement—on all relevant hosts. +- **Debug/Info Tasks:** Prints important group and network config when `debug_enabled`. +- **OCI CLI Install:** OS-dependent OCI CLI and tool installation. +- **Firewall/Networking:** Firewall rules and kernel module (br_netfilter) setup for all roles, tailored to Oracle CNE needs. +- **Package Install:** Operator, Control-Plane, and Worker receive relevant Oracle CNE packages and agent tap. +- **Service/Group Setup:** Oracle CNE API and agent service enablement and user group adjustments. +- **Certificate Lifecycle:** Extensive certificate/gen/copy for Kubernetes and webhooks. +- **Bootstrap:** Starts API server/agent with proper security context; avoids reruns via .ocne-provisioned sentinel. +- **Include/Task Orchestration:** Invokes further tasks for provisioning, CCM, Istio, Ceph, FSS, Kubectl, based on cluster state and toggles. + +## Dependencies & Relationships + +- Highly cross-linked: includes/invokes provision_ocne.yml, ceph_deployments.yml, fss_deployments.yml, provision_istio.yml, preconfig_oci_ccm.yml, etc. +- Requires: Oracle CNE packages, olcnectl, OCI CLI, compatible Oracle Linux hosts, correct group/host membership. +- Performs actions as root or via `username` from vars. + +## Output/Result + +- A fully initialized multi-node Oracle CNE cluster. +- All agents, services, and pre-requisites running with TLS/certificates in place. +- Optionally installed CCM, Istio, FSS, and supporting add-ons. + +## Example Run + +```bash +ansible-playbook deploy_ocne_full.yml diff --git a/ocne/docs/deploy_ocne_none.md b/ocne/docs/deploy_ocne_none.md new file mode 100644 index 0000000..a72cc1a --- /dev/null +++ b/ocne/docs/deploy_ocne_none.md @@ -0,0 +1,32 @@ +# deploy_ocne_none.yml Documentation + +## Purpose & Overview + +This playbook serves as a "no operation" (noop) placeholder for environments or situations where Oracle CNE does not need to be installed. It is referenced conditionally by orchestration playbooks to satisfy logic branches without side effects. + +## When to Use + +- When running test, demonstration, or controlled pipelines where Oracle CNE deployment should be skipped. +- As a logic target for inventory or playbook inclusion workflows that require a no-op phase. + +## Key Variables & Inputs + +- None required. + +## Task Breakdown + +- Prints an informational message confirming that no Oracle CNE deployment will occur. + +## Dependencies & Relationships + +- Invoked by create_instance.yml and main orchestration logic conditional on the `ocne_type` variable. +- Makes no changes or system modifications. + +## Output/Result + +- A clear debug/info message; no cloud or local resources changed. + +## Example Run + +```bash +ansible-playbook deploy_ocne_none.yml --limit operator diff --git a/ocne/docs/deploy_ocne_quick.md b/ocne/docs/deploy_ocne_quick.md new file mode 100644 index 0000000..6de3ca2 --- /dev/null +++ b/ocne/docs/deploy_ocne_quick.md @@ -0,0 +1,48 @@ +# deploy_ocne_quick.yml Documentation + +## Purpose & Overview + +Performs a streamlined, "quick" installation of Oracle Cloud Native Environment (Oracle CNE) using the olcnectl quick install mode. Brings up API server, control plane, and worker nodes in a single step (with or without LB), creates necessary cloud integration (CCM, Istio, FSS, Ceph), sets up OCI user/group config, and records provisioning details. + +## When to Use + +Use this playbook: + +- To rapidly deploy Oracle CNE for lab, demo, or testing where speed and simplicity are the priority. +- When the number of control plane nodes or inventory determines the optimal quick vs. HA style install. + +## Key Variables & Inputs + +- `operator_node`, `control_plane_nodes`, `worker_nodes`: String lists of node hosts. +- `private_load_balancer_ip_addresses`: Used for LB integration if >1 control plane. +- `username`: User for privileged/cloud config on the operator node. +- Feature toggles (from default_vars.yml): `use_lb`, `use_oci_ccm`, `use_istio`, `use_fss`, `add_ceph_deployments`. +- Other included variable files for sub-tasks. + +## Task Breakdown + +- **Debug Info:** Print role/host groups as configured. +- **Repo & Package Setup:** Set up Oracle LCNE repos and install olcnectl. +- **Quick Provisioning:** + - If single control plane: use olcnectl provision with just operator+control+worker. + - If multiple control planes/LB: extends provision command to include `--load-balancer` with endpoints. +- **Provision Marking:** Touches ~/.ocne-provisioned to track completed installs. +- **Post-Install Steps:** Adds user to olcne group, resets SSH, saves Oracle CNE config, and invokes config/feature modules (CCM, Istio, Ceph, FSS, Kubectl). +- **Conditional Includes:** Uses Ansible logic to only run features as toggled or required. + +## Dependencies & Relationships + +- Requires supporting playbooks and files: lb_vars.yml, preconfig_oci_ccm.yml, provision_oci_ccm.yml, provision_istio.yml, ceph_deployments.yml, fss_deployments.yml, provision_kubectl.yml. +- User/group setup and cloud variables must be present. +- For load balancer use, expects variables (private_load_balancer_ip_addresses) from earlier runs. + +## Output/Result + +- A provisioned Oracle CNE lab, single or multi-control-plane, with minimal user input. +- Integration with optional features as toggled in variables. +- Oracle CNE config saved for CLI/dev use. + +## Example Run + +```bash +ansible-playbook deploy_ocne_quick.yml --limit operator diff --git a/ocne/docs/deploy_ocne_vlan.md b/ocne/docs/deploy_ocne_vlan.md new file mode 100644 index 0000000..6a3cb3b --- /dev/null +++ b/ocne/docs/deploy_ocne_vlan.md @@ -0,0 +1,61 @@ +# deploy_ocne_vlan.yml Documentation + +## Purpose & Overview + +Automates the complete setup and deployment of an Oracle Cloud Native Environment (Oracle CNE) Kubernetes cluster on Oracle Cloud Infrastructure using VLAN networking. Covers advanced system prep, configures kernel/firewall, manages certificates, and installs Oracle CNE roles in a VLAN-context, supporting additional modules (CCM, Ceph, FSS, Kubectl). + +## When to Use + +Use this playbook: + +- To build a realistic, multi-node Oracle CNE cluster where VLAN-based networking is required or preferred over default subnet networking. +- When wider cloud feature integration (internal LB, VRRP, custom CIDRs) is needed for complex lab, test, or DMZ-like scenarios. + +## Key Variables & Inputs + +- Inventory host groups: `operator`, `controlplane`, `worker` +- Host- and IP-specific variables derived from ansible_ens5 interface +- vars_files: `default_vars.yml`, `oci_vars.yml` +- Feature toggles: `use_int_lb`, `use_vlan_full` +- Various pre-set IDs, domain names, and settings from earlier provisioning plays + +## Task Breakdown + +1. **System Prep (All Hosts):** + - SELinux local policy patch for iptables. + - Oracle CNE YUM repo config for OL8/OL9. + - Chrony NTP setup and enable. + - Swap disablement and persistent config. +2. **OCNE Install (Operator):** + - Writes bashrc profile with compartment IDs, locale. + - Installs oci-cli, jq tools per Oracle Linux version. + - Firewall rules for operator, internal/load balancers, VRRP as required. + - Kernel module and cni0/trusted zone firewall for container networking. + - Installs required Oracle CNE packages on all appropriate hosts/roles. + - Service enablement for API server and agents via systemd. + - User group updates and SSH connection resets. +3. **Certificate Handling:** + - Generates, distributes, and installs required TLS certificates for all nodes, webhooks, and CLI services. +4. **Manual Install (VLAN Mode):** + - If single control plane: runs olcnectl module create/validate/install (manual mode). + - If multi-control-plane/internal LB: handles LB virtual IP, VRRP firewall, module installs, and requires use_int_lb toggle. +5. **Post-Provisioning:** +6. + - Saves out Oracle CNE CLI config. + - Invokes provisions for kubectl and other support tools. + +## Dependencies & Relationships + +- Requires multiple included playbooks (ol8_repo_config.yml, ol9_repo_config.yml, provision_kubectl.yml, etc). +- Highly dependent on variable population and host targeting from earlier provisioning. +- Applies to environments with VLAN-specific infrastructure and requirements. + +## Output/Result + +- Multi-node Oracle CNE cluster configured for VLAN operation, with all agents, roles, and services correctly enabled and exposed. +- Properly networked cloud-native/test lab with full certificate management and add-on readiness. + +## Example Run + +```bash +ansible-playbook deploy_ocne_vlan.yml diff --git a/ocne/docs/fss_deployments.md b/ocne/docs/fss_deployments.md new file mode 100644 index 0000000..283bae0 --- /dev/null +++ b/ocne/docs/fss_deployments.md @@ -0,0 +1,43 @@ +# fss_deployments.yml Documentation + +## Purpose & Overview + +Generates and deploys Oracle Cloud Infrastructure File Storage Service (OCI FSS)-backed PersistentVolume (PV), PersistentVolumeClaim (PVC), and test pod YAML manifests to all control plane nodes. It enables Kubernetes workloads to consume OCI FSS storage for persistent data. + +## When to Use + +Use this playbook: + +- After OCI FSS resources are provisioned and fss_vars.yml is generated. +- To enable storage integration between Kubernetes and OCI FSS via NFS for test or production pods. + +## Key Variables & Inputs + +- `fss_vars.yml`: Variable file that provides FSS NFS export path, IP addresses, and required storage info. +- `groups['controlplane']`: Inventory group that designates nodes to receive the YAMLs. +- `username`: OS user context for file deployment and permissions. + +## Task Breakdown + +- **Variable Load:** Loads all OCI FSS configuration (paths, IPs) from fss_vars.yml. +- **Manifests Creation:** + - Renders fss-pv.yaml from fss_pv.j2 (PersistentVolume config). + - Renders fss-pvc.yaml from fss_pvc.j2 (PersistentVolumeClaim for consumption). + - Renders fss-pod.yaml from fss_pod.j2 (demo/test pod mounting the PVC). +- **Deployment:** Each manifest is placed in the home directory of each control plane host, with correct permissions. + +## Dependencies & Relationships + +- Depends on prior completion of create_fss.yml (and fss_vars.yml population). +- Templated using fss_pv.j2, fss_pvc.j2, fss_pod.j2 from ocne/templates/. +- Used from main cluster install or post-provisioning as add-on to enable apps to use NFS storage. + +## Output/Result + +- Each control plane node receives a full set of PV, PVC, and pod manifests ready for `kubectl apply`. +- Enables seamless Kubernetes-to-OCI-FSS storage integration. + +## Example Run + +```bash +ansible-playbook fss_deployments.yml diff --git a/ocne/docs/host_assign_vlan_ip.md b/ocne/docs/host_assign_vlan_ip.md new file mode 100644 index 0000000..9ad20f9 --- /dev/null +++ b/ocne/docs/host_assign_vlan_ip.md @@ -0,0 +1,46 @@ +# host_assign_vlan_ip.yml Documentation + +## Purpose & Overview + +Assigns static VLAN IPv4 addresses to all cluster nodes (Operator, Control-Plane, Worker) in OCI using the nmcli tool. Ensures network connectivity and complete mesh trust (SSH known_hosts) for subsequent cluster operations that rely on predictable VLAN addressing. + +## When to Use + +Use this playbook: + +- After VLAN resources are provisioned and before cluster bootstrapping or role assignment. +- To ensure all hosts have deterministic, unambiguous VLAN IPs and that SSH trust is pre-loaded. + +## Key Variables & Inputs + +- `ansible_ens5`: Host interface fact used for addressing and validation. +- `group_names`: Used to assign correct addresses per host role. +- `groups['controlplane']`, `groups['worker']`, `groups['all']`: Define node pools for assignment loops. +- `username`: Used for SSH known_hosts population step. +- `debug_enabled`: Enables per-node debug output. + +## Task Breakdown + +1. **VLAN IP Assignment:** + - Operator: 10.0.12.100/24 + - Control-plane: 10.0.12.1XX/24 (XX based on index in group) + - Worker: 10.0.12.2XX/24 (XX based on index in group) + - Uses nmcli for connection management on interface ens5. +2. **Gather facts:** Refreshes Ansible facts after changes. +3. **Debug (optional):** Outputs hostvars for troubleshooting. +4. **SSH Trust Prep:** + - Uses ssh-keyscan to pre-accept fingerprints for all node-to-node connections (when cluster size >=2). + +## Dependencies & Relationships + +- Requires nmcli and working network interface on each node. +- Commonly used post-VLAN creation from create_vlan.yml and pre-setup before Oracle CNE or K8s installs. + +## Output/Result + +- Each cluster node receives a role-specific VLAN IP and has all other nodes' fingerprints trusted for SSH, minimizing connection errors in clustered playbooks. + +## Example Run + +```bash +ansible-playbook host_assign_vlan_ip.yml diff --git a/ocne/docs/host_setup.md b/ocne/docs/host_setup.md new file mode 100644 index 0000000..8725973 --- /dev/null +++ b/ocne/docs/host_setup.md @@ -0,0 +1,56 @@ +# host_setup.yml Documentation + +## Purpose & Overview + +Performs baseline OS/user/SSH/firewall setup on each cluster node before advanced playbook orchestration. Handles user creation, password, sudo, SSH keys, local config, trust relationships, and diagnostics for cloud-native automation environments. + +## When to Use + +Use this playbook: + +- Immediately after provisioning a cluster VM or bare-metal node, before running key deployment or orchestration playbooks. +- To guarantee users, keys, SSH trust, and locale/firewall diagnostics are consistent across all target nodes. + +## Key Variables & Inputs + +- `username`: The Linux user to be created and configured on each host. +- `user_default_password`: Initial password for the new user (hashed at creation). +- `private_key`: Local SSH private key for use in setting authorized_keys. +- `groups['all']`: Node list for populating trust and key distribution. +- `my_subnet_domain_name`: Used to set fully-qualified host addresses in known_hosts. +- Debug variables: `debug_enabled` for optional diagnostics and additional logging. +- Retry tuning: `max_retries`, `retry_delay` (optional override). + +## Task Breakdown + +1. **Setup Loop and Retry Handling:** + - Tasks run in a block with self-rescue loops; will retry up to `max_retries`. +2. **Connection & Readiness:** + - Waits for SSH/connectivity, re-fetches facts. +3. **User and Auth Setup:** + - Creates user and sets password, group, sudoers (password-less), and locale. + - Generates and fetches SSH keys. + - Sets up authorized_keys for seamless Ansible operations. +4. **Trust/Key Distribution:** + - Copies local key to each host, populates trusted keys to all inventory peers. + - SSH known_hosts pre-populated using hostnames, subnets, and IPs (minimizes runtime prompts/failures). +5. **Firewall/Debug (optional):** + - Optionally enables dropped packet logging for investigation. +6. **Rescue Tasks:** + - If setup fails, waits and retries up to max_retries, printing diagnostics and messaging. + +## Dependencies & Relationships + +- Called from create_instance.yml and other cluster bring-up playbooks. +- Prepares nodes for automation, reducing friction in SSH and host key setup for all Ansible logic that follows. + +## Output/Result + +- Each node is accessible, has password-less SSH/Ansible access, consistent locale, and correct user/group setup. +- SSH trust and keys ready for Ansible and application orchestration. +- Hardened against common setup failures due to robust self-retry. + +## Example Run + +```bash +ansible-playbook host_setup.yml diff --git a/ocne/docs/ol8_repo_config.md b/ocne/docs/ol8_repo_config.md new file mode 100644 index 0000000..c5f6345 --- /dev/null +++ b/ocne/docs/ol8_repo_config.md @@ -0,0 +1,38 @@ +# ol8_repo_config.yml Documentation + +## Purpose & Overview + +Configures all necessary Oracle Oracle Cloud Native Environment (Oracle CNE) YUM repositories for Oracle Linux 8 hosts. Ensures that only required/compatible repositories are enabled, and older or conflicting ones are disabled, prior to package installation. + +## When to Use + +Use this playbook: + +- When provisioning or resetting any Oracle Linux 8-based VM/instance for Oracle CNE, Kubernetes, or support package installation. +- As a prerequisite step for installing Oracle CNE components or updating the platform on OL8. + +## Key Variables & Inputs + +- `ol8_enable_repo`: Names of current repositories to enable (from default_vars.yml). +- `ol8_disable_repo`: Legacy or obsolete repositories to disable (from default_vars.yml). + +## Task Breakdown + +- **Install olcne release package:** Ensures the Oracle CNE release repo is present. +- **Enable Current Repos:** Sets all primary Oracle CNE/Oracle Linux 8 repositories required for new installs. +- **Disable Old/Conflicting Repos:** Shuts off outdated or conflict-prone YUM repo sources. + +## Dependencies & Relationships + +- Must be run as root (via become). +- Typically called by higher-level deployment playbooks prior to Oracle CNE install. +- Closely paired with ol9_repo_config.yml for OL9 support. + +## Output/Result + +- Host is left with the latest/official Oracle CNE and OL8 YUM repositories enabled, safer package updates/installations, and fewer repo conflicts. + +## Example Run + +```bash +ansible-playbook ol8_repo_config.yml diff --git a/ocne/docs/ol9_repo_config.md b/ocne/docs/ol9_repo_config.md new file mode 100644 index 0000000..a9b3d4f --- /dev/null +++ b/ocne/docs/ol9_repo_config.md @@ -0,0 +1,38 @@ +# ol9_repo_config.yml Documentation + +## Purpose & Overview + +Configures Oracle Cloud Native Environment (Oracle CNE) YUM repositories on Oracle Linux 9. Ensures hosts only use up-to-date, compatible package sources for deploying Oracle CNE/Kubernetes and disables legacy or conflicting repos. + +## When to Use + +Use this playbook: + +- When building or updating OL9-based Oracle Linux nodes for Oracle CNE automation. +- Prior to package installation, component update, or if repo configurations have changed. + +## Key Variables & Inputs + +- `ol9_enable_repo`: YUM repo(s) to enable for OL9 (from default_vars.yml). +- `ol9_disable_repo`: YUM repo(s) to disable for OL9. + +## Task Breakdown + +- **Install olcne release package:** Adds required Oracle CNE repo stubs for OL9 platform. +- **Enable Current Repos:** Enables modern, required Oracle CNE-specific and base OS repos. +- **Disable Old/Conflicting Repos:** Turns off outdated or experimental sources for reliability and support. + +## Dependencies & Relationships + +- Must be run as root. +- Sibling to ol8_repo_config.yml (OL8 equivalent). +- Generally called early in OCI cluster and Oracle CNE deployments. + +## Output/Result + +- The node is fully prepared with all required repositories for Oracle CNE install on OL9, reducing chances of package/test failures due to repo mismatch. + +## Example Run + +```bash +ansible-playbook ol9_repo_config.yml diff --git a/ocne/docs/preconfig_oci_ccm.md b/ocne/docs/preconfig_oci_ccm.md new file mode 100644 index 0000000..9dcb58d --- /dev/null +++ b/ocne/docs/preconfig_oci_ccm.md @@ -0,0 +1,36 @@ +# preconfig_oci_ccm.yml Documentation + +## Purpose & Overview + +Prepares essential cloud environment configuration for Oracle Cloud Infrastructure Cloud Controller Manager (OCI CCM) integration by populating mandatory OCI IDs as bash environment variables. + +## When to Use + +Use this playbook: + +- After OCI infrastructure (network, subnets, compartments) is provisioned and oci_vars.yml is available. +- Before installing/configuring any component that relies on these IDs as shell environment variables (OCI CCM daemon, scripts, cluster bootstrap). + +## Key Variables & Inputs + +- `oci_vars.yml`: Contains `my_compartment_id`, `my_vcn_id`, `my_subnet_id` from prior runs. +- `username`: User whose .bashrc gets updated. + +## Task Breakdown + +- **Load Variables:** Reads OCI IDs and other vars from oci_vars.yml. +- **Update .bashrc:** Appends `export` lines for compartment, VCN, and subnet OCIDs, making them available for new shell sessions and runtime scripts/services. + +## Dependencies & Relationships + +- Relies on oci_vars.yml, which should be generated via earlier provisioning. +- Often paired with further CCM or integration playbooks. + +## Output/Result + +- User’s ~/.bashrc includes key cloud OCIDs for CCM or operator scripts. + +## Example Run + +```bash +ansible-playbook preconfig_oci_ccm.yml diff --git a/ocne/docs/provision_istio.md b/ocne/docs/provision_istio.md new file mode 100644 index 0000000..cbd7bd7 --- /dev/null +++ b/ocne/docs/provision_istio.md @@ -0,0 +1,41 @@ +# provision_istio.yml Documentation + +## Purpose & Overview + +Configures and installs the Istio service mesh on an Oracle CNE Kubernetes environment by templating the Istio load balancer configuration and invoking `olcnectl` to create and install the Istio module. + +## When to Use + +Use this playbook: + +- To automate setup of the Istio ingress/service mesh in new or existing OCI-based Kubernetes clusters managed by Oracle CNE. +- After the core environment and cluster have been provisioned, and ocne_provision indicates completion. + +## Key Variables & Inputs + +- `username`: User context for creation/installation tasks. +- `ocne_provision.stat.exists`: Controls conditional execution (must be true for module creation). +- Other environment variables (from prior provisioning) and templates. + +## Task Breakdown + +- **Templating:** Renders istio-lb.yaml manifest from istio_lb.j2 with custom parameters. +- **Istio Module Creation:** Uses `olcnectl` to create the Istio module, referencing cluster and profile via CLI. +- **Debug (optional):** Prints stdout for troubleshooting or validation. +- **Module Installation:** Installs Istio on the targeted environment. +- **Debug (optional):** Prints output from installation step. + +## Dependencies & Relationships + +- Relies on istio_lb.j2 template for configuration. +- `olcnectl` must be installed and available under the selected user. +- Must run after a successful Oracle CNE cluster deployment (`ocne_provision.stat.exists`). + +## Output/Result + +- Instantiated and installed Istio service mesh within the Oracle CNE cluster, ready for ingress and advanced mesh features. + +## Example Run + +```bash +ansible-playbook provision_istio.yml diff --git a/ocne/docs/provision_kubectl.md b/ocne/docs/provision_kubectl.md new file mode 100644 index 0000000..245825f --- /dev/null +++ b/ocne/docs/provision_kubectl.md @@ -0,0 +1,39 @@ +# provision_kubectl.yml Documentation + +## Purpose & Overview + +Enables non-root access to the Kubernetes cluster for all control plane hosts by ensuring correct placement of kubectl configuration files and making kube CLI accessible from login shells. + +## When to Use + +Use this playbook: + +- After initializing an Oracle CNE/Kubernetes cluster and confirming /etc/kubernetes/admin.conf exists. +- Any time you want to enable a user (default: operator) on all control plane machines to use `kubectl` without root privileges or sudo. + +## Key Variables & Inputs + +- `groups['controlplane']`: Nodes to receive kubeconfigs. +- `username`: Target OS user for kubectl privilege. +- `empty_cp_nodes`: Controls if some control plane nodes are skipped (zero/edge cases). + +## Task Breakdown + +- **.kube Directory:** Creates ~/.kube with proper permissions for each target user. +- **Copy Config:** Copies /etc/kubernetes/admin.conf to /home//.kube/config on every control plane node. +- **Export KUBECONFIG:** Appends correct export statement to the `.bashrc` for each user, enabling automatic kubectl context on shell login. + +## Dependencies & Relationships + +- Requires Ansible `become` for file creation/copying. +- Must be run after Oracle CNE/Kubernetes install and before administrative operations. +- Downstream playbooks and user sessions depend on a working ~/.kube/config. + +## Output/Result + +- On every control plane machine, the target user can run kubectl immediately after login, no sudo required. + +## Example Run + +```bash +ansible-playbook provision_kubectl.yml diff --git a/ocne/docs/provision_oci_ccm.md b/ocne/docs/provision_oci_ccm.md new file mode 100644 index 0000000..5638027 --- /dev/null +++ b/ocne/docs/provision_oci_ccm.md @@ -0,0 +1,45 @@ +# provision_oci_ccm.yml Documentation + +## Purpose & Overview + +Configures and deploys the Oracle Cloud Infrastructure Cloud Controller Manager (OCI CCM) module on the cluster, including the required firewall ingress/egress rules for K8s cloud integration and load balancer services. + +## When to Use + +Use this playbook: + +- After a successful Oracle CNE Kubernetes install when you want the cluster to have full OCI-native cloud integration—especially for Service Type=LoadBalancer and automatic networking. +- Any time you want to be sure CCM is installed and functional, such as during lab, CI, or self-managed cluster builds. + +## Key Variables & Inputs + +- `groups['controlplane']`, `groups['worker']`: Hosts needing firewall rule updates. +- `oci_vars.yml`: Must be loaded with current OCI config/OCIDs. +- `username`: User context for provisioning and module installation. +- `ocne_provision.stat.exists`: Controls conditional deployment. +- Cloud OCID variables: `my_compartment_id`, `my_vcn_id`, `my_subnet_id`. +- `debug_enabled`: (Optional) Enables detailed step-by-step printout. + +## Task Breakdown + +- **Firewall Configuration:** Opens port 10256/tcp for oci-ccm, and 30000-32767/tcp for LB services (on all control plane and worker nodes). +- **OCI Credential Ingestion:** Reads the latest OCID information from oci_vars.yml. +- **Istio/Cluster Diagnostic Prints:** Optional info printout aids troubleshooting. +- **OCI CCM Module Creation/Install:** + - Uses `olcnectl` to create and install the oci-ccm K8s module, leveraging instance principals and current K8s context. +- **Debug:** Prints standard install outputs stepwise when requested. + +## Dependencies & Relationships + +- Heavily depends on all prior OCI/Oracle CNE provisioning and network/resource state. +- Must be executed as the user/operator who owns the cluster context. +- Sibling step to other feature modules (Istio, Ceph, FSS, Kubectl). + +## Output/Result + +- A running OCI CCM deployment backing Service Type=LoadBalancer, advanced cloud integration, and dynamic networking in the K8s cluster. + +## Example Run + +```bash +ansible-playbook provision_oci_ccm.yml diff --git a/ocne/docs/provision_ocne.md b/ocne/docs/provision_ocne.md new file mode 100644 index 0000000..151676b --- /dev/null +++ b/ocne/docs/provision_ocne.md @@ -0,0 +1,48 @@ +# provision_ocne.yml Documentation + +## Purpose & Overview + +Performs a manual installation of the Oracle Cloud Native Environment (Oracle CNE) Kubernetes platform. It leverages the `olcnectl` CLI to create the environment, initialize K8s modules (with optional LB support), validate, and install the cluster, then saves config. + +## When to Use + +Use this playbook: + +- When automating Oracle CNE installs in "manual" mode (rather than quick/compact). +- When your cluster needs explicit differentiation of control plane layouts (single vs. multi, load balancer vs. not). +- As an orchestrated step in full OCI automation or for reproducible demo/lab environments. + +## Key Variables & Inputs + +- `operator_nodes`, `control_nodes`, `worker_nodes`: Node selection strings for API server, CP, and worker roles. +- `private_load_balancer_ip_addresses`: For clustered API endpoint in multi-CP, LB use cases. +- `ocne_registry_location`: Container registry source for K8s images. +- `use_lb`: Controls which config path is taken (LB vs. non-LB). +- `username`: The privilege user running `olcnectl` and provisioning. +- Cluster certificate references for secure install (optional). +- `debug_enabled`: Toggles diagnostic output. +- see default_vars.yml and deploy playbooks for more (many inputs inherited). + +## Task Breakdown + +- **Manual (Non-LB) Install Path:** Runs environment and K8s module create/validate/install with just the API/CP entries. +- **Manual LB Path:** Loads LB vars, runs `olcnectl` with `--load-balancer` and correct host/IP layout. +- **Debug (optional):** Prints install output result. +- **Provision Sentinel:** Touches `~/.ocne-provisioned` if successful. +- **Config Save:** Exports fresh Oracle CNE config for CLI/dev use. + +## Dependencies & Relationships + +- Requires ocne_registry_location, nodes, certs, and correct user context. +- Touches and uses ~user/ state to track provisioning. +- Sibling/alternative to deploy_ocne_* and create_instance.yml orchestrations. + +## Output/Result + +- Complete, validated, and installed Oracle CNE Kubernetes cluster (config saved). +- Clear, idempotent state via provision marker file for future automation safety. + +## Example Run + +```bash +ansible-playbook provision_ocne.yml diff --git a/ocne/docs/pvc.j2.md b/ocne/docs/pvc.j2.md new file mode 100644 index 0000000..5456f88 --- /dev/null +++ b/ocne/docs/pvc.j2.md @@ -0,0 +1,41 @@ +# pvc.j2 Template Documentation + +## Purpose + +Defines a PersistentVolumeClaim for Kubernetes to dynamically provision and bind to a CephFS-backed storage volume using the rook-cephfs StorageClass. + +## How the Template is Used + +- Provided as a ready-to-apply manifest by automation or included with test/demo storage assets. +- Users/operators can `kubectl apply -f pvc.yaml` to request shared, persistent storage. +- Integrates with the Rook operator and dynamically creates a volume in the CephFS storage pool. + +## Key Variables & Substitutions + +- No Jinja2 dynamic substitutions—template is static. + +## Rendered Example + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: cephfs-pvc +spec: + accessModes: + - ReadWriteMany + resources: + requests: + storage: 1Gi + storageClassName: rook-cephfs +``` + +## Special Logic + +- Assigns storageClassName rook-cephfs for dynamic volume management. +- Enables multiple pods to mount this volume (ReadWriteMany). + +## Related Files + +- Consumed together with cluster.j2, filesystem.j2, storageclass.j2 (CephFS storage stack). +- A core storage request object for rook/ceph-based clusters. diff --git a/ocne/docs/templates/cluster.j2.md b/ocne/docs/templates/cluster.j2.md new file mode 100644 index 0000000..a1ac19a --- /dev/null +++ b/ocne/docs/templates/cluster.j2.md @@ -0,0 +1,51 @@ +# cluster.j2 Template Documentation + +## Purpose + +Defines a Kubernetes `CephCluster` custom resource for use with Rook, configuring a full Ceph storage cluster for use as a backend for persistent storage in the environment. + +## How the Template is Used + +- Rendered by ceph_deployments.yml and distributed to every control plane node. +- Consumed by the `rook-ceph-operator` or any workflow needing to instantiate a Ceph cluster via `kubectl apply -f cluster.yaml`. +- Forms the foundation for all block/persistent storage within the K8s infrastructure. + +## Key Variables & Substitutions + +- This template has no Jinja2 substitutions; it is rendered as a static YAML manifest. + +## Rendered Example + +```yaml +apiVersion: ceph.rook.io/v1 +kind: CephCluster +metadata: + name: rook-ceph + namespace: rook +spec: + cephVersion: + image: container-registry.oracle.com/olcne/ceph:v17.2.5 + imagePullPolicy: Always + allowUnsupported: false + dataDirHostPath: /var/lib/rook + mon: + count: 3 + allowMultiplePerNode: false + dashboard: + enabled: false + storage: + useAllNodes: true + useAllDevices: false + deviceFilter: sdb +``` + +## Special Logic + +- No loops or conditionals; intended to be copied verbatim to the cluster. +- Default device assignment is to `/dev/sdb`, using all nodes for storage. + +## Related Files + +- Rendered by: ceph_deployments.yml (see its documentation). +- Consumed by: Rook/Ceph operator in the cluster. +- Closely associated with toolbox.j2, filesystem.j2, storageclass.j2, pvc.j2, vm.j2 as part of full storage stack. diff --git a/ocne/docs/templates/egress_security_rules.j2.md b/ocne/docs/templates/egress_security_rules.j2.md new file mode 100644 index 0000000..7491b73 --- /dev/null +++ b/ocne/docs/templates/egress_security_rules.j2.md @@ -0,0 +1,37 @@ +# egress_security_rules.j2 Template Documentation + +## Purpose + +Defines default egress security rules for cloud instance networking in OCI. Used as a variables file for dynamic security rule creation by Ansible playbooks during provisioning. + +## How the Template is Used + +- Rendered and included by playbooks such as create_instance.yml. +- Loaded via Ansible's include_vars to produce a variable named `instance_egress_security_rules`. +- Used as input to OCI network/security module to set up firewall rules for outbound traffic for new instances/subnets. + +## Key Variables & Substitutions + +- No Jinja2 variables or substitutions; a static set of YAML rules is rendered. + +## Rendered Example + +```yaml +instance_egress_security_rules: + - destination: "0.0.0.0/0" + protocol: 6 + - destination: "10.0.0.0/24" + protocol: 17 +``` + +## Special Logic + +- The list provides two default egress rules: + - Allow all TCP outbound to the internet (destination 0.0.0.0/0, protocol 6). + - Allow all UDP outbound to 10.0.0.0/24 (protocol 17), mirroring default cloud security best practice. +- No dynamic templating. + +## Related Files + +- Rendered by: create_instance.yml and potentially other infrastructure playbooks managing network security lists. +- Works with ingress_security_rules.j2 as a complementary pair for full firewall configuration. diff --git a/ocne/docs/templates/filesystem.j2.md b/ocne/docs/templates/filesystem.j2.md new file mode 100644 index 0000000..298acf8 --- /dev/null +++ b/ocne/docs/templates/filesystem.j2.md @@ -0,0 +1,48 @@ +# filesystem.j2 Template Documentation + +## Purpose + +Defines a Kubernetes `CephFilesystem` custom resource for Rook, setting up a distributed CephFS filesystem for use as a persistent, POSIX-compliant shared volume by the cluster. + +## How the Template is Used + +- Rendered by ceph_deployments.yml and deployed to each control plane node. +- Applied to the cluster by the Rook operator to create and manage CephFS storage pools, metadata servers, and provide multi-node file system access. + +## Key Variables & Substitutions + +- This template is fully static: no Jinja2 substitutions are present. + +## Rendered Example + +```yaml +apiVersion: ceph.rook.io/v1 +kind: CephFilesystem +metadata: + name: mycephfs + namespace: rook +spec: + metadataPool: + replicated: + size: 3 + dataPools: + - name: replicated + replicated: + size: 3 + preserveFilesystemOnDelete: true + metadataServer: + activeCount: 1 + activeStandby: true +``` + +## Special Logic + +- Replicated pools for both metadata and data, each with `size: 3` for durability. +- Single active metadata server with standby enabled. +- Filesystem is not deleted even when the CRD is removed (`preserveFilesystemOnDelete: true`). + +## Related Files + +- Rendered by: ceph_deployments.yml. +- Consumed by: Rook operator inside the K8s cluster. +- Used together with cluster.j2, storageclass.j2, pvc.j2, toolbox.j2, and vm.j2 for a full storage stack. diff --git a/ocne/docs/templates/fss_pod.j2.md b/ocne/docs/templates/fss_pod.j2.md new file mode 100644 index 0000000..509775f --- /dev/null +++ b/ocne/docs/templates/fss_pod.j2.md @@ -0,0 +1,48 @@ +# fss_pod.j2 Template Documentation + +## Purpose + +Provides a Kubernetes Pod manifest that tests persistent storage via a mounted OCI File Storage Service (FSS) PersistentVolumeClaim. + +## How the Template is Used + +- Rendered and distributed to control plane nodes by fss_deployments.yml. +- Demonstrates correct pod-to-PVC-to-PV-to-FSS integration in the Kubernetes cluster. +- Used by operators/testers to verify persistent storage setup for the lab is functional—writes timestamps to /data/out.txt on the NFS mount. + +## Key Variables & Substitutions + +- No Jinja2 variables or substitutions; this template is fully static. + +## Rendered Example + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: app +spec: + containers: + - name: app + image: ghcr.io/oracle/oraclelinux:8 + command: ["/bin/bash"] + args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 5; done"] + volumeMounts: + - name: persistent-storage + mountPath: /data + volumes: + - name: persistent-storage + persistentVolumeClaim: + claimName: fss-pvc +``` + +## Special Logic + +- Mounts /data from a PVC named fss-pvc. +- Infinite loop writes timestamps to persist data; pod can be deleted/recreated and data will persist. + +## Related Files + +- Rendered by: fss_deployments.yml. +- Consumes: fss-pvc.yaml, which defines the PVC. +- Used for: Storage integration validation and demonstration. diff --git a/ocne/docs/templates/fss_pv.j2.md b/ocne/docs/templates/fss_pv.j2.md new file mode 100644 index 0000000..f30e2cd --- /dev/null +++ b/ocne/docs/templates/fss_pv.j2.md @@ -0,0 +1,47 @@ +# fss_pv.j2 Template Documentation + +## Purpose + +Defines a Kubernetes PersistentVolume (PV) resource for binding to Oracle Cloud Infrastructure File Storage Service (OCI FSS) using the CSI driver. + +## How the Template is Used + +- Rendered by fss_deployments.yml, provided with live FSS IDs and IPs. +- Responsible for provisioning a PV resource in the cluster, which is then claimable by persistent workloads via corresponding PVCs. + +## Key Variables & Substitutions + +- `file_system_id`: The OCID of the created FSS file system. +- `mount_target_ip_address`: IP address of the FSS mount target. +- `export_path`: NFS export path; rendered as part of the OCI FSS setup. +- These are set/generated by create_fss.yml and passed in via fss_vars.yml. + +## Rendered Example + +```yaml +apiVersion: v1 +kind: PersistentVolume +metadata: + name: fss-pv +spec: + capacity: + storage: 50Gi + volumeMode: Filesystem + accessModes: + - ReadWriteMany + persistentVolumeReclaimPolicy: Retain + csi: + driver: fss.csi.oraclecloud.com + volumeHandle: ocid1.filesystem.oc1..xx:10.0.0.99:/fss-ocne +``` + +## Special Logic + +- Leverages Jinja2 variable substitutions for dynamic infrastructure. +- CSI driver string hard-coded for OCI FSS. + +## Related Files + +- Rendered by: fss_deployments.yml. +- Consumed together with fss_pvc.j2 and fss_pod.j2. +- Relies on and related to file outputs from create_fss.yml (fss_vars.yml). diff --git a/ocne/docs/templates/fss_pvc.j2.md b/ocne/docs/templates/fss_pvc.j2.md new file mode 100644 index 0000000..7a6e459 --- /dev/null +++ b/ocne/docs/templates/fss_pvc.j2.md @@ -0,0 +1,44 @@ +# fss_pvc.j2 Template Documentation + +## Purpose + +Defines a Kubernetes PersistentVolumeClaim (PVC) resource that binds to the statically-created FSS PersistentVolume, allowing pods to request and consume persistent NFS storage in Oracle Cloud. + +## How the Template is Used + +- Rendered and distributed by fss_deployments.yml. +- Used by demo/test pods (see fss_pod.j2) and any other K8s workload requiring shared, persistent storage. +- Matches to a single provisioned PV (`fss-pv`) for static NFS mounting. + +## Key Variables & Substitutions + +- No Jinja2 variables are present; purely static manifest. + +## Rendered Example + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: fss-pvc +spec: + accessModes: + - ReadWriteMany + storageClassName: "" + resources: + requests: + storage: 50Gi + volumeName: fss-pv +``` + +## Special Logic + +- `storageClassName: ""` ensures binding to a statically-created PV (not dynamic provisioning). +- Binds exactly to the previously defined PV (`volumeName: fss-pv`). +- Allows multiple pods to mount (ReadWriteMany). + +## Related Files + +- Rendered by: fss_deployments.yml. +- Consumed by: pods such as fss_pod.j2. +- Binds to: fss_pv.j2-generated PV resource. diff --git a/ocne/docs/templates/fss_vars.j2.md b/ocne/docs/templates/fss_vars.j2.md new file mode 100644 index 0000000..0d539d5 --- /dev/null +++ b/ocne/docs/templates/fss_vars.j2.md @@ -0,0 +1,37 @@ +# fss_vars.j2 Template Documentation + +## Purpose + +Dynamically generates a YAML variable file exposing all required connection parameters for the OCI File Storage Service (FSS) provisioned by automation. Makes IDs and addresses available to other playbooks and templates. + +## How the Template is Used + +- Rendered by create_fss.yml as `fss_vars.yml`. +- This vars file is then included by fss_deployments.yml and any other playbooks/templates needing FSS state. +- Enables dynamic, environment-specific binding of PersistentVolumes via Jinja2 substitution. + +## Key Variables & Substitutions + +- `file_system_id`: The OCID for the created FSS file system. +- `mount_target_ip_address`: The primary private IP assigned to the FSS mount target. +- `export_path`: The NFS export path provisioned by the FSS export. + +These values are substituted by Ansible when create_fss.yml is run, coming from OCI provision module outputs. + +## Rendered Example + +```yaml +file_system_id: ocid1.filesystem.oc1..aaa +mount_target_ip_address: 10.0.0.45 +export_path: /fss-ocne +``` + +## Special Logic + +- Entire template is rendered via variable substitution; no logic or conditionals. +- Used as a live config/vars file for later FSS/K8s playbooks. + +## Related Files + +- Generated by: create_fss.yml. +- Consumed by: fss_deployments.yml, fss_pv.j2, and subsequent FSS/NFS automation steps. diff --git a/ocne/docs/templates/ingress_security_rules.j2.md b/ocne/docs/templates/ingress_security_rules.j2.md new file mode 100644 index 0000000..c21d65f --- /dev/null +++ b/ocne/docs/templates/ingress_security_rules.j2.md @@ -0,0 +1,73 @@ +# ingress_security_rules.j2 Template Documentation + +## Purpose + +Defines the default and optional ingress security rules for instances in OCI, consumed by Ansible `include_vars` for programmatic firewall/network list creation. + +## How the Template is Used + +- Rendered by playbooks such as create_instance.yml as a dynamic YAML variable file (`instance_ingress_security_rules`). +- Consumed by OCI networking modules to configure security list ingress rules for all VMs in the cluster. + +## Key Variables & Substitutions + +- Templated on the Ansible variable `use_ingress_lb`: + - If true, opens HTTP (80/TCP) and HTTPS (443/TCP) from all sources. + - Always allows SSH (22/TCP), local VCN traffic, and certain ICMP codes. +- Static entries for internal and cloud-classic networking requirements. + +## Rendered Example (when use_ingress_lb is true) + +```yaml +instance_ingress_security_rules: + - source: "0.0.0.0/0" + protocol: 6 + tcp_options: + destination_port_range: + max: 22 + min: 22 + - source: "0.0.0.0/0" + protocol: 6 + tcp_options: + destination_port_range: + max: 80 + min: 80 + - source: "0.0.0.0/0" + protocol: 6 + tcp_options: + destination_port_range: + max: 443 + min: 443 + - source: "0.0.0.0/0" + protocol: 1 + icmp_options: + type: 3 + code: 4 + - source: "10.0.0.0/24" + protocol: 6 + tcp_options: + destination_port_range: + min: 1 + max: 65535 + - source: "10.0.0.0/24" + protocol: 17 + udp_options: + destination_port_range: + min: 1 + max: 65535 + - source: "10.0.0.0/24" + protocol: 1 + icmp_options: + type: 3 +``` + +## Special Logic + +- Uses Jinja2 `{% if use_ingress_lb %}` to conditionally expand the security list. +- Supports both public and local VCN communication. +- Fully YAML, no further logic or looping. + +## Related Files + +- Rendered/consumed by: create_instance.yml or other network provisioning playbooks. +- Used with: egress_security_rules.j2 for comprehensive firewalling. diff --git a/ocne/docs/templates/istio_lb.j2.md b/ocne/docs/templates/istio_lb.j2.md new file mode 100644 index 0000000..1b4c185 --- /dev/null +++ b/ocne/docs/templates/istio_lb.j2.md @@ -0,0 +1,40 @@ +# istio_lb.j2 Template Documentation + +## Purpose + +Defines a YAML configuration fragment to customize the behavior of the Istio ingress gateway LoadBalancer for Oracle Cloud Infrastructure (OCI) Kubernetes clusters. + +## How the Template is Used + +- Rendered by provision_istio.yml and used as the profile input for `olcnectl module create` during Istio installation. +- Applies annotation-based configuration to the Istio ingressgateway Service to control load balancer characteristics in OCI. +- Ensures the Istio LB is provisioned as internal, flexible, and not security-list managed. + +## Key Variables & Substitutions + +- This template is static (no Jinja2 substitutions), encoding all required annotations. + +## Rendered Example + +```yaml +components: + ingressGateways: + - name: istio-ingressgateway + k8s: + serviceAnnotations: + service.beta.kubernetes.io/oci-load-balancer-security-list-management-mode: "None" + service.beta.kubernetes.io/oci-load-balancer-internal: "true" + service.beta.kubernetes.io/oci-load-balancer-shape: "flexible" + service.beta.kubernetes.io/oci-load-balancer-shape-flex-min: "10" + service.beta.kubernetes.io/oci-load-balancer-shape-flex-max: "10" +``` + +## Special Logic + +- Configures the ingress gateway load balancer as INTERNAL-ONLY (not public-facing) with fixed bandwidth (via min/max). +- Disables OCI's security-list management for the LB (lets user handle via automation/explicit rules). + +## Related Files + +- Written and referenced from: provision_istio.yml. +- Intended for: Service annotations, customizing load balancer resources when using Istio on Oracle Kubernetes. diff --git a/ocne/docs/templates/lb_vars.j2.md b/ocne/docs/templates/lb_vars.j2.md new file mode 100644 index 0000000..c498521 --- /dev/null +++ b/ocne/docs/templates/lb_vars.j2.md @@ -0,0 +1,33 @@ +# lb_vars.j2 Template Documentation + +## Purpose + +Dynamically generates a YAML variable file with the OCI private load balancer primary IP address after it is provisioned by automation. + +## How the Template is Used + +- Rendered by create_lb.yml as the file lb_vars.yml. +- The resulting variable is referenced by playbooks and templates that require knowledge of the Load Balancer endpoint, including application profiles (e.g. Istio, quick/HA install, manual config). +- Ensures the runtime value is inserted exactly as provisioned in OCI. + +## Key Variables & Substitutions + +- `private_load_balancer_ip_addresses`: An array of IP objects as returned by the OCI module. + - Only the first IP (primary) is extracted and set as `private_load_balancer_ip_addresses` in the output YAML. +- Jinja2 substitution is used to insert the live provisioned value. + +## Rendered Example + +```yaml +private_load_balancer_ip_addresses: 10.0.0.25 +``` + +## Special Logic + +- Extracts only the first element of the OCI return array. +- Used as a variable file; no additional looping or conditionals. + +## Related Files + +- Created by: create_lb.yml. +- Consumed by: quick/HA deployment playbooks, Istio/OCI annotation profiles, explain/config docs. diff --git a/ocne/docs/templates/myenvironment.j2.md b/ocne/docs/templates/myenvironment.j2.md new file mode 100644 index 0000000..2a8015b --- /dev/null +++ b/ocne/docs/templates/myenvironment.j2.md @@ -0,0 +1,58 @@ +# myenvironment.j2 Template Documentation + +## Purpose + +Generates a YAML configuration file for defining an Oracle CNE environment—used as a global config source for `olcnectl`/automation-driven cluster bootstrapping. + +## How the Template is Used + +- Can be rendered by automation to a variable file, then passed to `olcnectl environment create --config-file`. +- Supports single or multi-control-plane, with/without load balancer setup. +- Populates environment, global settings (certs, API endpoint), module configuration, control plane/worker nodes, and all required cluster bootstrap values. + +## Key Variables & Substitutions + +- `ocne_registry_location`: Container registry address for K8s images. +- `use_lb`, `lb_ip`: Conditional block for inserting LB information. +- `groups['controlplane']`, `groups['worker']`: Jinja2 looped listings to declare all nodes. +- `username`: Used in external IP certificate paths. + +### Conditional Blocks + +- LB config only included if `use_lb` is true. +- Node lists populated via Jinja2 for-loops. + +## Rendered Example (simplified) + +```yaml +environments: + - environment-name: myenvironment + globals: + api-server: 127.0.0.1:8091 + ... + modules: + - module: kubernetes + name: mycluster + args: + container-registry: registry.example.com/olcne + load-balancer: 10.0.0.25:6443 # if use_lb + control-plane-nodes: + - cp-01:8090 + - cp-02:8090 + worker-nodes: + - worker-01:8090 + selinux: enforcing + restrict-service-externalip-ca-cert: /home/myuser/certificates/ca/ca.cert + restrict-service-externalip-tls-cert: /home/myuser/certificates/restrict_external_ip/node.cert + restrict-service-externalip-tls-key: /home/myuser/certificates/restrict_external_ip/node.key +``` + +## Special Logic + +- Jinja2 conditionals and loops to insert/exclude or enumerate config values based on deployment/inventory state. +- Suitable for all current automation/olcnectl CLI config requirements. + +## Related Files + +- May be generated by provision_ocne.yml or for direct operator usage. +- Used by: `olcnectl` environment/module commands with `--config-file`. diff --git a/ocne/docs/templates/oci_vars.j2.md b/ocne/docs/templates/oci_vars.j2.md new file mode 100644 index 0000000..1002f2f --- /dev/null +++ b/ocne/docs/templates/oci_vars.j2.md @@ -0,0 +1,40 @@ +# oci_vars.j2 Template Documentation + +## Purpose + +Emits essential networking and compartment variables for Oracle Cloud Infrastructure (OCI) automation and playbook chaining. This is the central config "glue" between infrastructure/app provisioning and runtime/cluster setup. + +## How the Template is Used + +- Rendered by provisioning playbooks (e.g., create_instance.yml). +- Consumed via `include_vars: oci_vars.yml` by other playbooks to leverage the correct compartment, VCN, subnet, and optional VLAN details. +- Ensures environment-specific values are always up to date without manual edits. + +## Key Variables & Substitutions + +- `my_compartment_id`: The OCID of the OCI compartment to deploy infra into. +- `my_vcn_id`: The OCID of the VCN for your environment. +- `my_subnet_id`: The OCID of the K8s subnet. +- `my_subnet_domain_name`: FQDN for K8s subnet DNS. +- `my_vlan_id`: The OCID of the created VLAN (only if use_vlan is set). +- Jinja2 conditionals to include VLAN ID only if VLAN is enabled. + +## Rendered Example + +```yaml +my_compartment_id: ocid1.compartment.oc1..aaaa +my_vcn_id: ocid1.vcn.oc1..bbbb +my_subnet_id: ocid1.subnet.oc1..cccc +my_subnet_domain_name: subnet1.vcn1.oraclevcn.com +my_vlan_id: ocid1.vlan.oc1..dddd # only if VLAN enabled +``` + +## Special Logic + +- Conditional inclusion of my_vlan_id based on inventory/vars (Jinja2 `{% if use_vlan %}`). +- All variable values are auto-populated by prior provisioning steps—no hardcoding. + +## Related Files + +- Generated by: create_instance.yml and/or network provisioning playbooks. +- Consumed by: preconfig_oci_ccm.yml, cluster creation, CCM, LB, and most downstream automation logic. diff --git a/ocne/docs/templates/ocir_vars.j2.md b/ocne/docs/templates/ocir_vars.j2.md new file mode 100644 index 0000000..3b9d91a --- /dev/null +++ b/ocne/docs/templates/ocir_vars.j2.md @@ -0,0 +1,35 @@ +# ocir_vars.j2 Template Documentation + +## Purpose + +Exports registry (OCIR) metadata—repository ID, name, and namespace—for the use of automation and downstream playbooks configuring container images, access, and K8s integration. + +## How the Template is Used + +- Rendered by create_ocir.yml to create ocir_vars.yml. +- This YAML is then included and referenced wherever registry configuration, access, or deployments are needed across the environment (cluster bootstrap, image pulls, etc). + +## Key Variables & Substitutions + +- `ocir_id`: OCID of the OCI container registry. +- `ocir_name`: Name of the provisioned OCI registry. +- `ocir_namespace`: The namespace assigned in OCIR. +- All are Jinja2 variables set at runtime based on OCI API results. + +## Rendered Example + +```yaml +ocir_id: ocid1.containerrepo.oc1..abcd +ocir_name: demo/oraclelinux-cloud +ocir_namespace: demo123 +``` + +## Special Logic + +- Static key emission per invocation/call—no conditionals, no loops. +- Each value fully customized by current OCI registry state. + +## Related Files + +- Written by: create_ocir.yml. +- Included by: any downstream playbook or script requiring OCI registry info. diff --git a/ocne/docs/templates/storageclass.j2.md b/ocne/docs/templates/storageclass.j2.md new file mode 100644 index 0000000..1224278 --- /dev/null +++ b/ocne/docs/templates/storageclass.j2.md @@ -0,0 +1,46 @@ +# storageclass.j2 Template Documentation + +## Purpose + +Defines a Kubernetes StorageClass (rook-cephfs) for dynamic provisioning of CephFS-backed PersistentVolumes using the Rook CSI driver. + +## How the Template is Used + +- Applied to clusters (often by automation) so that PersistentVolumeClaim objects referencing storageClassName: rook-cephfs will result in dynamic Ceph volumes. +- Connects the CSI/Rook provisioner to the Ceph cluster, providing a central interface for persistent/shared storage. + +## Key Variables & Substitutions + +- No Jinja2 dynamic variables; template is static. + +## Rendered Example + +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: rook-cephfs +provisioner: rook.cephfs.csi.ceph.com +parameters: + clusterID: rook + fsName: mycephfs + pool: mycephfs-replicated + csi.storage.k8s.io/provisioner-secret-name: rook-csi-cephfs-provisioner + csi.storage.k8s.io/provisioner-secret-namespace: rook + csi.storage.k8s.io/controller-expand-secret-name: rook-csi-cephfs-provisioner + csi.storage.k8s.io/controller-expand-secret-namespace: rook + csi.storage.k8s.io/node-stage-secret-name: rook-csi-cephfs-node + csi.storage.k8s.io/node-stage-secret-namespace: rook +reclaimPolicy: Delete +``` + +## Special Logic + +- Assigns all required secret/config keys for CephFS dynamic volume management. +- Sets cluster/pool info consistent with other storage templates. +- `reclaimPolicy: Delete` ensures PVs are removed when claims are deleted. + +## Related Files + +- Used by: pvc.j2 (for claim/bind). +- Connected with: cluster.j2, filesystem.j2, toolbox.j2 for complete Rook/Ceph FS stack automation. diff --git a/ocne/docs/templates/toolbox.j2.md b/ocne/docs/templates/toolbox.j2.md new file mode 100644 index 0000000..c986ecd --- /dev/null +++ b/ocne/docs/templates/toolbox.j2.md @@ -0,0 +1,78 @@ +# toolbox.j2 Template Documentation + +## Purpose + +Defines a Kubernetes Deployment for running the Rook Ceph toolbox pod, which equips the cluster with a pre-built CLI toolset for Ceph management, troubleshooting, and operational actions. + +## How the Template is Used + +- Deployed by ceph_deployments.yml to every control plane node as toolbox.yaml. +- Provides on-demand access to ceph/rados/rook commands within the cluster, using real-time config and keyring data for secure admin operations. + +## Key Variables & Substitutions + +- No dynamic Jinja2 substitution; configuration is static apart from container runtime environment/secret/ConfigMap bindings. + +## Rendered Example (abridged) + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: rook-ceph-tools + namespace: rook +spec: + replicas: 1 + template: + spec: + containers: + - name: rook-ceph-tools + image: container-registry.oracle.com/olcne/ceph:v17.2.5 + command: + - /bin/bash + - -c + - | + # Inline ceph config/keyring and endpoint update script (see template for details) + env: + - name: ROOK_CEPH_USERNAME + valueFrom: + secretKeyRef: + name: rook-ceph-mon + key: ceph-username + volumeMounts: + - mountPath: /etc/ceph + name: ceph-config + - name: mon-endpoint-volume + mountPath: /etc/rook + - name: ceph-admin-secret + mountPath: /var/lib/rook-ceph-mon + readOnly: true + volumes: + - name: ceph-admin-secret + secret: + secretName: rook-ceph-mon + optional: false + items: + - key: ceph-secret + path: secret.keyring + - name: mon-endpoint-volume + configMap: + name: rook-ceph-mon-endpoints + items: + - key: data + path: mon-endpoints + - name: ceph-config + emptyDir: {} +``` + +## Special Logic + +- Startup script replicates toolbox.sh logic inline for endpoint/keyring/config file management. +- Watches and updates ceph.conf live as MON endpoints or failovers occur. +- Reads secrets from env or files for keyring population; maintains secure (non-root) context. +- Tolerates brief node unreachable status for resilience. + +## Related Files + +- Rendered by: ceph_deployments.yml. +- Used with: cluster.j2, filesystem.j2, storageclass.j2, providing a CLI for CephFS and cluster/storage troubleshooting. diff --git a/ocne/docs/templates/vm.j2.md b/ocne/docs/templates/vm.j2.md new file mode 100644 index 0000000..1365f6c --- /dev/null +++ b/ocne/docs/templates/vm.j2.md @@ -0,0 +1,80 @@ +# vm.j2 Template Documentation + +## Purpose + +Defines a KubeVirt VirtualMachine intended for the OCNE lab/demo stack, combining OCI container images, persistent (CephFS) volumes, and cloud-init for user and SSH provisioning. + +## How the Template is Used + +- Deployed as part of ceph_deployments.yml (vm.yaml). +- Demonstrates best-practice pattern for creating VMs attached to dynamically provisioned CephFS-backed volumes. +- Integrates cloud-native OCI registry, persistent storage, and cloud-init initialization in a single K8s manifest. + +## Key Variables & Substitutions + +- All config is static; no Jinja2 variables. + +## Rendered Example (abridged) + +```yaml +apiVersion: kubevirt.io/v1 +kind: VirtualMachine +metadata: + name: ol9-nocloud +spec: + running: true + template: + spec: + terminationGracePeriodSeconds: 30 + networks: + - name: foo + pod: {} + domain: + cpu: + cores: 2 + sockets: 1 + threads: 1 + resources: + requests: + memory: 2048M + devices: + interfaces: + - name: foo + masquerade: {} + ports: + - port: 80 + - port: 22 + disks: + - name: containerdisk + disk: + bus: virtio + - name: mypvcdisk + disk: + bus: virtio + - name: cloudinitdisk + disk: + bus: virtio + volumes: + - name: containerdisk + containerDisk: + image: fra.ocir.io/OCIR_NAMESPACE/demo/oraclelinux-cloud:9.4-terminal + imagePullSecret: ocirsecret + - name: mypvcdisk + persistentVolumeClaim: + claimName: cephfs-pvc + - name: cloudinitdisk + cloudInitNoCloud: + secretRef: + name: vmi-userdata-secret +``` + +## Special Logic + +- Combines OCI Registry image, CephFS volume, and cloud-init for rapid, automated VM onboarding and persistence. +- Exposes network ports for SSH and HTTP; tolerates native K8s pod networking. +- Termination/cleanup resilience with controlled grace period. + +## Related Files + +- Rendered by: ceph_deployments.yml as vm.yaml. +- Consumed with: pvc.j2, storageclass.j2, cloud-init secrets, demonstrating full lab provisioning path. diff --git a/ol/docs/README.md b/ol/docs/README.md new file mode 100644 index 0000000..9511882 --- /dev/null +++ b/ol/docs/README.md @@ -0,0 +1,190 @@ +# Oracle Linux Lab Automation – Playbooks & Template Documentation + +## Overview + +This directory provides complete documentation for every Ansible playbook and Jinja2 template found in `linux-virt-labs/ol/`. The goal is to support onboarding, troubleshooting, extension, and integration for users of the Oracle Linux Automation Suite across on-premise, VM, and OCI workflows. + +You’ll find an individual Markdown (`.md`) doc for each playbook or template, summarizing purpose, key variables, main logic, dependencies, and real-world usage. + +--- + +## Deploy Oracle Linux Using These Ansible Playbooks + +**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/ol + ``` + +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 2 repository. + + a. Deploy a single Oracle Linux instance configured with the following: + + - 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" + ``` + + This deploys a new Oracle Linux instance with a working libvirt environment ready for you to setup and install an Oracle CNE 2 install of your choice. + + b. The default values (see `defaults.yml`) can be overridden by creating a separate file with the revised definition to be created. This example deploys two Oracle Linux 8 instances with: + + - A non-root user account with sudo access + - Key-based SSH, also known as password-less SSH, between the hosts + - Access to the Internet + + - i. Increase the Boot volume size, install libvirt, and use Oracle Linux 9. + + ```shell + cat << EOF | tee instances.yml > /dev/null + compute_instances: + 1: + instance_name: "ol-node-01" + type: "server" + 2: + instance_name: "ol-node-02" + type: "server" + passwordless_ssh: true + EOF + ``` + + - ii. Deploy the Oracle Linux instances configured using the custom configuration created in `instances.yml`: + + ```shell + ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" + ``` + + **Note:** The free lab environment requires the extra variable `localhost_python_interpreter`, which sets `ansible_python_interpreter` for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules. Either remove, or update this variable to match your system's requirements. + + The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command. + + > **Important:** Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab. + +--- + +## Documentation Table + +### Playbooks – Index + +| Playbook | Summary | Related Templates/Files | +| - | - | - | +| [block.yml](./block.md) | Provisions and attaches OCI block storage volumes to instances. | Used by build.yml & create_instance.yml | +| [build.yml](./build.md) | Automates compute instance launch & storage, inventories hosts. | block.yml | +| [create_instance.yml](./create_instance.md) | Top-level orchestrator: provisions network, VMs, SSH, and teardown | All major plays/templates | +| [default_vars.yml](./default_vars.md) | Central variable set for all hosts, provisioning, toggles. | Included everywhere | +| [download_ol_iso.yml](./download_ol_iso.md) | Automates Oracle Linux ISO downloads for local builds. | | +| [host_setup.yml](./host_setup.md) | Prepares hosts: users, SSH, sudo, locale, retry-on-fail. | | +| [passwordless_setup.yml](./passwordless_setup.md) | Ensures password-less SSH between all hosts. | | +| [provision_kvm_vm.yml](./provision_kvm.md) | Provisions/reconfigures KVM VMs by pulling images, defining VMs. | vm_template.j2 | +| [provision_kvm.yml](./provision_kvm.md) | Installs/configures KVM hypervisor, delegates to provision_kvm_vm | | +| [provision_podman.yml](./provision_podman.md) | Installs Podman/containers, OL8/9+ variant support. | | +| [provision_vbox.yml](./provision_vbox.md) | Sets up Oracle VirtualBox, repo, keys, and extpack. | | +| [provision_vnc.yml](./provision_vnc.md) | Enables TigerVNC/graphical login for remote desktop access. | | +| [requirements.yml](./requirements.md) | Tracks required Galaxy collections for roles/modules. | | +| [update_all_rpms.yml](./update_all_rpms.md) | Automates dnf update for all packages, safe kernel reboot. | | + +### Templates – Index + +| Template | Description & Usage | +| --- | --- | +| [egress_security_rules.j2](./templates/egress_security_rules.j2.md) | Default egress: allow all TCP outbound | +| [ingress_security_rules.j2](./templates/ingress_security_rules.j2.md) | Conditional ingress rules for all services (SSH, Nginx, NFS, etc.) | +| [oci_vars.j2](./templates/oci_vars.j2.md) | Emits OCI resource IDs for automation | +| [vm_template.j2](./templates/vm_template.j2.md) | Parameterized libvirt/KVM XML template for VMs | + +--- + +## Tree Listing + +```markdown +└-─ ol +    ├── block.md +    ├── build.md +    ├── create_instance.md +    ├── default_vars.md +    ├── download_ol_iso.md +    ├── host_setup.md +    ├── passwordless_setup.md +    ├── provision_kvm_vm.md +    ├── provision_kvm.md +    ├── provision_podman.md +    ├── provision_vbox.md +    ├── provision_vnc.md +    ├── README.md +    ├── requirements.md + ├── update_all_rpms.md +    └── templates +       ├── egress_security_rules.j2.md +       ├── ingress_security_rules.j2.md +       ├── oci_vars.j2.md +       └── vm_template.j2.md +``` + +--- + +## Relationships and Workflow + +- **create_instance.yml** is the top-level orchestrator, importing and orchestrating nearly every play/template. +- **build.yml** handles instance creation; relies on block.yml for customizable storage logic. +- **passwordless_setup.yml** and **host_setup.yml** are called for every new environment/user bootstrapping. +- **provision_kvm.yml** and **provision_kvm_vm.yml** manage hypervisors and local/remote VM lab builds, leveraging vm_template.j2 for flexible infrastructure. +- Security (egress/ingress) is always set by including or rendering the Jinja2 templates, enabling full firewall and network policy automation. +- Requirements.yml is to be processed before any playbook run for reliable workflow automation. + +--- + +## Onboarding & Usage + +1. **Install dependencies:** + + ```bash + ansible-galaxy collection install -r requirements.yml + ``` + +1. **Customize variables as needed** by editing default_vars.yml for your desired lab topology, feature toggles, and credential patterns. + +1. **Run create_instance.yml** for a full deploy/teardown cycle: + + ```bash + ansible-playbook create_instance.yml + ``` + +1. **Review per-playbook and per-template `.md` docs** for detailed task breakdowns, parameters, and troubleshooting information. +1. Use individual utility plays (provision_podman, provision_vbox, etc.) as demanded by your test or real-world scenario. + +--- + +## Lab Patterns & Best Practices + +- All files are mapped 1:1 to documentation in this directory +- Playbooks/templates should be updated together; documentation is maintained in sync +- Follow README-driven navigation to understand relationships, index, and workflow entrypoints + +--- diff --git a/ol/docs/block.md b/ol/docs/block.md new file mode 100644 index 0000000..be3a278 --- /dev/null +++ b/ol/docs/block.md @@ -0,0 +1,36 @@ +# block.yml Documentation + +## Purpose & Overview + +Provisions and attaches block storage volumes to Oracle Cloud Infrastructure (OCI) compute instances. Handles multiple attachment scenarios: batch or per-item, using both global and item-level toggles. + +## When to Use + +Use within other automation flows (e.g., build.yml, create_instance.yml) to automate, control, and trace all block volume provisioning and instance attachment in OCI. + +## Key Variables & Inputs + +- `block_devices`: List of device letters (e.g., ['b','c','d'])—controls device naming. +- `my_availability_domain`, `my_compartment_id`: OCI context values to locate all resources. +- `block_volume_size_in_gbs`: Size of each volume. +- `instance_id`, `volume_type`: Target compute instance and attachment type. +- `add_block_storage`, `item.value.add_bv`: Toggles: global and per-item. +- `block_count`: Number of block devices to attach. + +## Task Breakdown + +- Creates a new OCI blockstorage volume per device, naming each uniquely (blockvolume-vdX). +- Records the volume OCID for downstream usage. +- Attaches each volume to the running instance with a uniquely named device path, ensuring ordering/safety. +- Supports both all-host (add_block_storage) and itemized (item.value.add_bv) modes. +- Robust retries and idempotency baked in. + +## Dependencies & Relationships + +- Used by: build.yml (via include_tasks), create_instance.yml (via imported roles/tasks). +- Requires Oracle OCI Ansible collection. +- Must run after the target compute instance is available in OCI. + +## Output/Result + +- One or more OCI block volumes per instance, named/attached for full OS/automation visibility. diff --git a/ol/docs/build.md b/ol/docs/build.md new file mode 100644 index 0000000..ddc2dd4 --- /dev/null +++ b/ol/docs/build.md @@ -0,0 +1,40 @@ +# build.yml Documentation + +## Purpose & Overview + +Automates launching OCI compute instances, with support for both paravirtualized (PV) and iSCSI boot volumes. Configures VNICs, public/private IPs, attaches extra block storage, and handles host inventory. + +## When to Use + +Use as the main instance provisioning playbook when standing up a set of OL-based VMs in OCI, supporting flexible boot/storage, multiple network types, and readiness for further setup. + +## Key Variables & Inputs + +- `instance_shape`, `instance_ocpus`, `instance_memory`: Machine specs. +- `my_availability_domain`, `my_compartment_id`, `my_subnet_id`: OCI resource locations. +- `ol_image_id`: Source image for the boot volume. +- `item`: Host definition from inventory. +- `volume_type`: "paravirtualized" or "iscsi". +- `block_devices`, `block_count`, `add_block_storage`, etc.: Block volume controls. + +## Task Breakdown + +- Conditional logic: Two main flows for instance creation (PV and iSCSI). +- Launches compute instance, sets facts/hostvars, prints results if debug is enabled. +- Fetches and sets public/private IPs for the instance. +- Invokes block.yml (in a loop) to attach and provision block volumes. +- Adds hosts to Ansible in-memory and .ini file inventories to enable post-create configuration. +- Handles host group assignment, SSH configuration, and proxy support. +- Optionally adds a special host-level block volume. +- All retries, error handling, and idempotency included. + +## Dependencies & Relationships + +- Relies on block.yml for storage attachment logic. +- Requires upstream definition of cloud/network/image parameters. +- Integrated into create_instance.yml (as an included role/task). +- Uses facts, hostvars, and templates (ingress/egress security rules) for dynamic deployment. + +## Output/Result + +- Full OCI instance deployment, ready for login, automation, and further roles. diff --git a/ol/docs/create_instance.md b/ol/docs/create_instance.md new file mode 100644 index 0000000..a417599 --- /dev/null +++ b/ol/docs/create_instance.md @@ -0,0 +1,39 @@ +# create_instance.yml Documentation + +## Purpose & Overview + +Top-level playbook for orchestrating all stages of deployment in the Oracle Linux automation lab: networking, VM provisioning (OCI/cloud and local), configuration, package update, host setup, destruction, and more. + +## When to Use + +Use this playbook to provision full test/deployment environments in OCI or on local hypervisors, handle all configuration, SSH, and variable orchestration, or to destroy/deprovision when teardown is needed. + +## Key Variables & Inputs + +- Extensive: see default_vars.yml for base variables including compute_instances, OS/image specs, resource group toggles, storage, VM parameters, toggles for VNC/KVM/Podman/VirtualBox, and more. +- Uses inventory groups (server/vbox/etc) to control scope. + +## Task Breakdown + +- **Facts & Cloud State Discovery:** Reads OCI config and facts, compartment, region, AD, builds network, determines images, prepares variables. +- **Network & Security Provisioning:** VCN/subnet setup, route tables, security lists, ingress/egress via Jinja2 templates. +- **Provisioning Steps:** + - Launches VMs (via build.yml), sets up hosts, SSH, proxy, group assignment. + - Password-less SSH and key setup (password-less_setup.yml, host_setup.yml). + - KVM/PV/Local hypervisor deployment (imports/executes child playbooks for KVM, VirtualBox etc. as needed). + - Handles VNC/GNOME provisioning, ISO download, etc, by importing associated playbooks. + - Outputs result details and SSH info for further automation. + - Optional controlled pause step. +- **Teardown/Destruction:** + - Designed for safe teardown of all cloud and local resources (with explicit fail checks, resource removal, and state cleanup). + +## Dependencies & Relationships + +- Imports and delegates to: build.yml, host_setup.yml, passwordless_setup.yml, download_ol_iso.yml, provision_kvm.yml, provision_podman.yml, provision_vnc.yml, provision_vbox.yml, update_all_rpms.yml. +- Uses egress_security_rules.j2, ingress_security_rules.j2, oci_vars.j2, block.yml. +- Requires all dependencies present in requirements.yml. + +## Output/Result + +- Fully provisioned, multi-VM, networked lab environment, ready for application workloads, admin, or teardown. +- Inventory, SSH, and config primed for extension or further automation. diff --git a/ol/docs/default_vars.md b/ol/docs/default_vars.md new file mode 100644 index 0000000..50246cd --- /dev/null +++ b/ol/docs/default_vars.md @@ -0,0 +1,28 @@ +# default_vars.yml Documentation + +## Purpose & Overview + +Defines all key variables, toggles, and defaults for instance creation, VNC/KVM/Podman/VirtualBox provisioning, user credentials, and more in the Oracle Linux automation lab stack. + +## When to Use + +Use as the central variables file for include_vars or vars_files in playbooks to ensure consistent, DRY provisioning for all automation targets and tools. + +## Key Variables & Inputs + +- **compute_instances:** List of lab VMs to provision, their names, types, and configs. +- **OS/Image Params:** Operating system, version, base image info for KVM/VBox, and associated SHA256 sum. +- **Resources:** RAM, vCPUs, block size/count, VM disks, networks. +- **Feature Toggles:** Use VNC/KVM/Podman/VBox/etc, boot volume strategy, password-less SSH. +- **User/Password Details:** User, group, default pass, ssh key, root pass. +- **Environment/Build:** Proxy config, region settings, update flags, hypervisor details, image/cert details. +- **Others:** Collection of advanced toggles to enable/disable NFS, HAProxy, OCFS2, etc. + +## Dependencies & Relationships + +- Used by: All major playbooks (build, create_instance, host_setup, etc.) +- Read by Jinja2 templates via vars_files/include_vars. + +## Output/Result + +- Parameterizes all hosts, automation tasks, and dependent templates for fully automated, reproducible deployments. diff --git a/ol/docs/download_ol_iso.md b/ol/docs/download_ol_iso.md new file mode 100644 index 0000000..6bdafaa --- /dev/null +++ b/ol/docs/download_ol_iso.md @@ -0,0 +1,34 @@ +# download_ol_iso.yml Documentation + +## Purpose & Overview + +Automates the download of Oracle Linux ISO images for local VM creation or bare-metal installation, using the Oracle public ISO repository. + +## When to Use + +Use to programmatically fetch the required Oracle Linux ISO (specified by version and update) on your lab host for KVM, VirtualBox, or physical machine builds. + +## Key Variables & Inputs + +- `ol_iso_version`: Oracle Linux major version (e.g., 8, 9, 10). +- `ol_update`: Update level to fetch (e.g., 4, 10). +- `username`: Target user for file ownership. +- `base_url`: The Oracle download base URL, default: https://yum.oracle.com/ISOS/OracleLinux (overridable) +- `vbox`/`server`: Host(s) that will perform the download. + +## Task Breakdown + +- Constructs the exact ISO URL based on version/update. +- Downloads the ISO to `/home/{{ username }}` on the target host. +- Ensures download is complete (retries up to 5 times), and sets file permissions. +- Registers and checks result for success (supports repeated or interrupted runs). + +## Dependencies & Relationships + +- Uses variables from default_vars.yml. +- Downstream requirement for VM/KVM installs needing local ISO image. +- Can share ISOs between roles/VM definitions for reproducibility. + +## Output/Result + +- Oracle Linux ISO image is present and ready for VM or bare-metal installation flows. diff --git a/ol/docs/host_setup.md b/ol/docs/host_setup.md new file mode 100644 index 0000000..3e0098f --- /dev/null +++ b/ol/docs/host_setup.md @@ -0,0 +1,34 @@ +# host_setup.yml Documentation + +## Purpose & Overview + +Prepares remote hosts for lifecycle management: ensures user account, sudo access, SSH configuration, root filesystem growth, and secure locale/permissions—all with robust connection and retry handling. + +## When to Use + +Include this playbook at the start of any host preparation flow (after initial provisioning and networking). Ensures Ansible and default users are correctly configured for further configuration or automation. + +## Key Variables & Inputs + +- `username`, `user_default_password`, `private_key`: User, password, and SSH key info. +- `max_retries`, `retry_delay`: Controls connection resilience and timed retries. +- `debug_enabled`: Toggles status/debug output. + +## Task Breakdown + +- Waits for connection or SSH reachability (handles proxy/non-proxy). +- Optionally grows root filesystem post-provisioning. +- Creates user, sets password, sudoers (NOPASSWD), and authorized SSH key. +- Configures locale/export in .bashrc. +- Creates .ansible tmp directory for temporary files/operations. +- Optionally logs denied packets via firewalld for troubleshooting. +- Implements retry and rescue mechanism—if setup fails, will wait and re-try processing. +- All commands are idempotent and allow for failed or interrupted provisioning runs to safely recover. + +## Dependencies & Relationships + +- Consumed by: create_instance.yml, initial provisioning flows, or anywhere user/account/config bootstrapping is required. + +## Output/Result + +- All remote hosts are fully configured for subsequent roles, automated workflows, and secure SSH-driven automation. diff --git a/ol/docs/passwordless_setup.md b/ol/docs/passwordless_setup.md new file mode 100644 index 0000000..01d74bb --- /dev/null +++ b/ol/docs/passwordless_setup.md @@ -0,0 +1,30 @@ +# passwordless_setup.yml Documentation + +## Purpose & Overview + +Automates generation and distribution of SSH keypairs, ensuring password-less SSH across all lab hosts/inventory. Sets up trusted host keys for seamless multi-host automation. + +## When to Use + +Run this playbook anytime new hosts are added, SSH keys need to be re-generated, or password-less SSH is required for orchestration, batch job flows, or VM automation. + +## Key Variables & Inputs + +- `username`: The OS user for whom SSH keys are set up. +- `groups['all']`: Inventory list for trust and key distribution. +- `debug_enabled`, `my_subnet_domain_name`: Toggles and additional host info. + +## Task Breakdown + +- Generates SSH keypair (openssh_keypair module) for the user if missing. +- Fetches the public key from each host into a local buffer. +- Loops through all hosts and populates authorized_keys with public keys, enabling cross-host access. +- Debug: Optionally prints hostvars and VNC subnet for troubleshooting/diagnostic purposes. +- Ensures all hosts have updated known_hosts, pre-populating fingerprints for secure, non-interactive connections. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and other initial provisioning/join flows. +- Must be run after base user is set up and SSH access is available. + +## Output/Result diff --git a/ol/docs/provision_kvm.md b/ol/docs/provision_kvm.md new file mode 100644 index 0000000..7ff44bb --- /dev/null +++ b/ol/docs/provision_kvm.md @@ -0,0 +1,33 @@ +# provision_kvm.yml Documentation + +## Purpose & Overview + +Provisions and configures a local KVM hypervisor environment—fully automated install/enable for virtualization packages, cockpit web UI, `firewalld` adjustments, and user access. Handles OL8 and OL9 with best-practice service setup. + +## When to Use + +Use to convert a fresh Oracle Linux system into a ready-to-use KVM hypervisor for lab/VM automation and local testing, or to reset/reconcile packages and user state on an existing system. + +## Key Variables & Inputs + +- `username`: User to be given hypervisor and GUI group permissions. +- `create_vm`: If true, child playbooks (provision_kvm_vm.yml) are auto-invoked for OL8/OL9 VMs. +- `default_vars.yml`, image variables: For VM builds. + +## Task Breakdown + +- Installs required packages for virtualization (differentiated by OL8 vs OL9 stack). +- Enables/starts libvirt, modular service sockets, and cockpit web interface. +- Adjusts `firewalld` to support libvirt control. +- Adds user to correct groups and resets SSH as needed. +- Delegates actual VM imaging and config to provision_kvm_vm.yml ("Deploy VM1"/"Deploy VM2" pattern). +- Focuses on reliability, maintains idempotency, allows repeated safe runs. +- Supports both major OL versions and future OL releases with modular handling. + +## Dependencies & Relationships + +- Consumed by: create_instance.yml as an imported playbook. +- Calls: provision_kvm_vm.yml for actual VM creation. +- Requires group setup/user creation and at least one base image to copy. + +## Output/Result diff --git a/ol/docs/provision_kvm_vm.md b/ol/docs/provision_kvm_vm.md new file mode 100644 index 0000000..295d8c9 --- /dev/null +++ b/ol/docs/provision_kvm_vm.md @@ -0,0 +1,37 @@ +# provision_kvm_vm.yml Documentation + +## Purpose & Overview + +Automates local virtual machine (VM) creation in a lab environment using community.libvirt and cloud-init, supporting repeatable builds for complex topologies. + +## When to Use + +Use to create base VMs (OL8, OL9, or other images) on KVM hypervisors in the Oracle Linux lab, ensuring images, meta-data, networking, and user SSH setup are all in place. + +## Key Variables & Inputs + +- `vm_name`, `base_image_name`, `base_image_url`, `base_image_sha`: Controls image source/naming. +- `libvirt_pool_dir`: Local VM image (qcow2) storage. +- `username`: OS user for SSH and cloud-init setup. +- `groups['all']`: For SSH trust keys. +- `vm_ram_mb`, `vm_vcpus`: Sizing/tuning. +- All variables are typically set upstream (e.g., in provision_kvm.yml playbook). + +## Task Breakdown + +- Gathers current VMs (prevents duplicate). +- Downloads and verifies the base image. +- Copies the image to a local pool, sets ownership for libvirt usage. +- Creates SSH keypair for cloud-init, user meta-data, and public key. +- Generates cloud-init ISO for nocloud provisioning. +- Defines the VM using a Jinja2-generated libvirt XML template (vm_template.j2). +- Starts the VM and ensures it comes online. +- Optionally deletes temporary file artifacts. + +## Dependencies & Relationships + +- Called by: provision_kvm.yml (may provision both OL8 and OL9 template-based VMs). +- Uses: vm_template.j2 for XML structure. +- Depends on libvirt, cloud-init, and standard KVM stack. + +## Output/Result diff --git a/ol/docs/provision_podman.md b/ol/docs/provision_podman.md new file mode 100644 index 0000000..96b6100 --- /dev/null +++ b/ol/docs/provision_podman.md @@ -0,0 +1,28 @@ +# provision_podman.yml Documentation + +## Purpose & Overview + +Installs Podman (and related container tools, including `podman-docker` and `conntrack`) and curl for running Linux containers. Handles differences between Oracle Linux 8/9/10. + +## When to Use + +Use to ready a server for modern container workflows, OCI image deployment, and OCI/Podman automation. Can be included as a child playbook of a larger provisioning/CI process. + +## Key Variables & Inputs + +- Host group: `server` +- OS version detection: differentiates install approach for OL8, OL9, OL10 + +## Task Breakdown + +- Installs the right set of container tools and dependencies per Oracle Linux version using dnf (tries/retries for robustness). +- Podman and podman-docker for container management (OL9/10), container-tools meta package for OL8. +- Installs `conntrack` and curl everywhere (dependency for K8s/minikube/network testing). + +## Dependencies & Relationships + +- Requires root/become. +- Used by: create_instance.yml or as a standalone utility playbook. +- May be invoked alongside other VM, VNC, KVM, or infra provisioning. + +## Output/Result diff --git a/ol/docs/provision_vbox.md b/ol/docs/provision_vbox.md new file mode 100644 index 0000000..8b11a64 --- /dev/null +++ b/ol/docs/provision_vbox.md @@ -0,0 +1,31 @@ +# provision_vbox.yml Documentation + +## Purpose & Overview + +Automates installation and configuration of Oracle VirtualBox, its extension pack, and supporting dependencies on an Oracle Linux lab host for VM creation and management. + +## When to Use + +Use to bootstrap a new VirtualBox hypervisor for lab/test/kitchen environments on OL8 systems (primarily intended for desktop or test-lab use cases). + +## Key Variables & Inputs + +- `virtualbox_version`, `virtualbox_extpack_version`: Determines which version (and extension pack) will be installed. +- `username`: Controls permissions/ownership. +- EPEL, RPM keys, repo configuration: for package management and VirtualBox repo. +- Defaults and proxy variables handled in upstream config. + +## Task Breakdown + +- Installs EPEL and required dependencies (kernel headers, gcc, make, etc). +- Adds RPM keys, configures the official VirtualBox repo. +- Installs the specified VirtualBox version via dnf/yum. +- Checks for existing extension packs; downloads and installs if missing. +- Handles known package/repo/re-keying order for idempotent deploys. + +## Dependencies & Relationships + +- Used by: create_instance.yml or as a dedicated VirtualBox lab setup playbook. +- Links with base images and downstream VM create scripts for full virtualized testbeds. + +## Output/Result diff --git a/ol/docs/provision_vnc.md b/ol/docs/provision_vnc.md new file mode 100644 index 0000000..1d61222 --- /dev/null +++ b/ol/docs/provision_vnc.md @@ -0,0 +1,31 @@ +# provision_vnc.yml Documentation + +## Purpose & Overview + +Installs, configures, and enables TigerVNC Server with GNOME desktop on OL lab VMs/servers for GUI and remote desktop access. + +## When to Use + +Use when you want to enable graphical (GNOME) interface and VNC-based graphical login for Oracle Linux hosts (VM or bare metal), useful for desktop/server testing. + +## Key Variables & Inputs + +- `vnc_port`: VNC port (display) to assign (per user). +- `vnc_default_password`: Password set for .vnc passwd. +- `username`: User to assign VNC login. +- `vnc_geometry`: VNC screen size (e.g., 1920x1080). + +## Task Breakdown + +- Installs "Server with GUI" package, TigerVNC server, and required modules. +- Sets system to graphical boot; configures vncserver systemd service for correct port. +- Updates vncserver.users and .vnc config files to assign geometry and session type. +- Prepares .vnc directories with correct ownership/permissions, generates password, and lock down access. +- Starts and enables the VNC service (systemd) using user-assigned service instance configuration. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and other automated "desktop" setups. +- Can be coordinated with VirtualBox/KVM or remote workstation deployment. + +## Output/Result diff --git a/ol/docs/requirements.md b/ol/docs/requirements.md new file mode 100644 index 0000000..1b80180 --- /dev/null +++ b/ol/docs/requirements.md @@ -0,0 +1,33 @@ +# requirements.yml Documentation + +## Purpose & Overview + +Lists all required Ansible Galaxy collections needed for the OL lab automation suite to function—including OCI, libvirt, community, postgresql, freeipa, and ovirt modules. + +## When to Use + +Install all required dependencies before running any playbook in the OL project, using + +```bash +ansible-galaxy collection install -r requirements.yml +``` + +to guarantee module compatibility and maximum automation portability. + +## Collections Specified + +- `ansible.posix`: Provides POSIX utilities for system and SSH config. +- `community.general`: Community-supported utilities for roles, core tasks, and integrations. +- `community.crypto`: Cryptographic and SSH key management (with pinned version constraint). +- `community.postgresql`: For PostgreSQL tasks/roles. +- `freeipa.ansible_freeipa`: FreeIPA support for identity/LAB systems. +- `community.libvirt`: KVM/libvirt/QEMU VM management, local lab modernization. +- `oracle.oci`: Oracle Cloud Infrastructure collection for all cloud resource management. +- `ovirt.ovirt`: For integration with Ovirt-based virtualization. + +## Dependencies & Relationships + +- Consumed automatically by Ansible and all playbooks in the OL lab. +- Up-to-date dependency management ensures playbooks, roles, and templates are compatible via tested, versioned modules. + +## Output/Result diff --git a/ol/docs/templates/egress_security_rules.j2.md b/ol/docs/templates/egress_security_rules.j2.md new file mode 100644 index 0000000..803a3a2 --- /dev/null +++ b/ol/docs/templates/egress_security_rules.j2.md @@ -0,0 +1,24 @@ +# egress_security_rules.j2 Documentation + +## Purpose & Overview + +Defines the default egress security rules for OCI instances in YAML format for automation inclusion. Enables unrestricted TCP outbound traffic from managed hosts. + +## When to Use + +Use as an include_vars input anywhere security list configuration is needed in automation or bootstrapping of Oracle Linux infrastructure for OCI (cloud or on-prem scenarios). + +## Key Variables & Substitutions + +- Static YAML structure, no Jinja2 substitutions. +- Exposes: + - `instance_egress_security_rules`: + - destination: "0.0.0.0/0" (all hosts) + - protocol: 6 (TCP) + +## Dependencies & Relationships + +- Used together with ingress_security_rules.j2 for full network policy. +- Typically included or rendered in create_instance.yml or cloud/network setup plays. + +## Output/Result diff --git a/ol/docs/templates/ingress_security_rules.j2.md b/ol/docs/templates/ingress_security_rules.j2.md new file mode 100644 index 0000000..e0ee67c --- /dev/null +++ b/ol/docs/templates/ingress_security_rules.j2.md @@ -0,0 +1,26 @@ +# ingress_security_rules.j2 Documentation + +## Purpose & Overview + +Defines dynamic ingress rules for OCI security lists, rendered by Jinja2 template logic into Ansible variables used to control access to Oracle Linux cloud or lab VMs based on feature toggles (HAProxy, Nginx, NFS, HA Quay, PCP, OCFS2, iSCSI). + +## When to Use + +Use as include_vars in playbooks wherever you want to configure per-feature or per-service firewall policies in a data-driven, repeatable manner (see create_instance.yml, build.yml). + +## Key Variables & Substitutions + +- `use_haproxy`, `use_nginx`, `use_nfs`, `use_quay_ha`, `use_pcp`, `use_ocfs2`, `use_iscsi`: Control which ports/services are opened for which protocols (TCP/UDP). +- Always opens SSH (22/TCP) from the internet. +- Conditional entries expose rules for app, HTTP, HTTPS, NFS, database, high-availability, storage, or monitoring protocols. +- Jinja2 logic ensures only relevant entries are included in final rendered YAML. + +## Dependencies & Relationships + +- Used in concert with egress_security_rules.j2 for full security policy. +- Injected into OCI security list configuration via Ansible tasks during initial host, VM, or environment provisioning. +- Variables can be toggled in default_vars.yml or at runtime via ansible-playbook -e. + +## Output/Result + +- Renders a variable set instance_ingress_security_rules for application in OCI security lists, with explicit rule entries per enabled service. diff --git a/ol/docs/templates/oci_vars.j2.md b/ol/docs/templates/oci_vars.j2.md new file mode 100644 index 0000000..2c3dc40 --- /dev/null +++ b/ol/docs/templates/oci_vars.j2.md @@ -0,0 +1,27 @@ +# oci_vars.j2 Documentation + +## Purpose & Overview + +Emits YAML config with core OCI resource IDs—compartment, VCN, subnet, and domain name—for Ansible-driven automation and template rendering. + +## When to Use + +Use this template to export current OCI resource IDs for use by other playbooks and templates that require orchestrated API access, security, or network context. + +## Key Variables & Substitutions + +- `my_compartment_id`: Target compartment OCID in OCI. +- `my_vcn_id`: VCN OCID. +- `my_subnet_id`: Subnet OCID. +- `my_subnet_domain_name`: Subnet's DNS-friendly name. +- All values are injected at runtime via Ansible variable system. + +## Dependencies & Relationships + +- Typically created by create_instance.yml or provisioning playbooks. +- Consumed by build.yml, block.yml, and security templates, ensuring all spawned resources are correctly referenced. +- Must be current and in sync with provisioned infrastructure for automated teardown or host/role updates. + +## Output/Result + +- YAML file with all major IDs ready to include in automation flows for accurate, robust, and repeatable lab setups. diff --git a/ol/docs/templates/vm_template.j2.md b/ol/docs/templates/vm_template.j2.md new file mode 100644 index 0000000..951700d --- /dev/null +++ b/ol/docs/templates/vm_template.j2.md @@ -0,0 +1,35 @@ +# vm_template.j2 Documentation + +## Purpose & Overview + +Defines a parameterized libvirt XML domain for Oracle Linux lab VMs, using Jinja2 variables for name, memory, CPU, disks, networking, and more. + +## When to Use + +Used by provision_kvm_vm.yml as the basis for creating new KVM VMs in the local lab/infrastructure, ensuring automated and reproducible machine builds. + +## Key Variables & Substitutions + +- `vm_name`: VM hostname. +- `vm_ram_mb`: Memory size (MB). +- `vm_vcpus`: vCPU count. +- `libvirt_pool_dir`: Directory for qcow2 images and ISO. +- `vm_net`: Name of network for VM NIC. +- Everything else (disk modeling, bus type, ISO filename, etc.) is dynamically generated per-run via upstream Ansible variables/playbooks. + +## Structure/Logic + +- OS: x86_64, Q35 chipset, hvm type. +- Boot: Hard disk default, CD-ROM (cloud-init ISO) included. +- Devices: Virtio for disk and network, random, QEMU agent, USB, console, controller, and secure defaults. +- Networks: Connects to `vm_net` via . +- Storage: Attach a qcow2 base disk and cloud-init ISO as CD-ROM for user/SSH setup. +- Fully compatible with KVM/QEMU/libvirt and standardized for Ansible-driven flows. + +## Dependencies & Relationships + +- Called directly from provision_kvm_vm.yml via `lookup('template', ...)`. +- All runtime variables are injected by parent playbook. +- Must be in sync with the actual disk images, cloud-init renderings, and Ansible inventory being built. + +## Output/Result diff --git a/ol/docs/update_all_rpms.md b/ol/docs/update_all_rpms.md new file mode 100644 index 0000000..9842f21 --- /dev/null +++ b/ol/docs/update_all_rpms.md @@ -0,0 +1,30 @@ +# update_all_rpms.yml Documentation + +## Purpose & Overview + +Automates updates for all installed Oracle Linux packages, ensuring hosts are up-to-date with the latest kernel and software. Can optionally trigger a controlled reboot if a new kernel is installed. + +## When to Use + +Use to keep all lab VMs or bare-metal hosts fully patched, compliant, and running the latest required updates. Run after provisioning or before critical tests/upgrades. + +## Key Variables & Inputs + +- Host groups: `server`, `vbox` +- `proxy_env`: Optional proxy settings for package download. + +## Task Breakdown + +- Uses `dnf` to update all packages to the latest version with retries for robustness. +- Executes needs-restarting to detect if a reboot is required after updates. +- If required, safely reboots the machine(s). +- debug_enabled variable can be set for verbose output and diagnosis. + +## Dependencies & Relationships + +- Requires default_vars.yml for host/user/high-level configuration. +- Often referenced as a task or imported playbook in create_instance.yml or similar top-level orchestrations. + +## Output/Result + +- System is updated to latest OS, security patches, and all software packages; will reboot if kernel or core system has changed. diff --git a/olam/docs/README.md b/olam/docs/README.md new file mode 100644 index 0000000..9d94c43 --- /dev/null +++ b/olam/docs/README.md @@ -0,0 +1,193 @@ +# Oracle Linux Automation Manager (OLAM) – Lab Playbook & Template Documentation + +## Overview + +This directory contains authoritative, onboarding-focused documentation for every Ansible playbook and Jinja2 template in the Oracle Linux Automation Manager lab (`linux-virt-labs/olam/`). + +- Each file is mapped 1:1 to a `.md` doc for easy navigation, troubleshooting, and extension. +- Operators, developers, and learners can find detailed usage, logic, and variable descriptions here. + +--- + +## Deploy Oracle Linux Automation Manager Using These Ansible Playbooks + +**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/olam + ``` + +1. Install the required collections. + + ```shell + ansible-galaxy collection install -r requirements.yml + ``` + +1. Update the Oracle Linux Instance Configuration. + + ```shell + cat << EOF | tee instances.yml > /dev/null + compute_instances: + 1: + instance_name: "olam-node" + type: "control" + olam_type: none + EOF + ``` + +1. Create an Inventory file. + + ```shell + cat << EOF | tee hosts > /dev/null + localhost ansible_connection=local ansible_connection=local ansible_python_interpreter=/usr/bin/python3.6 + EOF + ``` + +1. Deploy the lab environment. + + ```shell + ansible-playbook create_instance.yml -i hosts -e "@instances.yml" + ``` + + **Note:** The free lab environment requires the extra variable `localhost_python_interpreter`, which sets `ansible_python_interpreter` for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules. Either remove, or update this variable to match your system's requirements. + + The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command. + + > **Important:** Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab. + +--- + +## Documentation Table + +### Playbooks – Index + +| Playbook | Summary | Related Templates/Files | +| --- | --- | --- | +| [block.yml](./docs/olam-original/block.md) | Attaches OCI block storage volumes to compute nodes. | | +| [build.yml](./build.md) | Launch and inventory OCI instances, configures storage/net. | block.yml | +| [check_instance_available.yml](./check_instance_available.md) | Sanity and reachability check for lab/OCI hosts. | | +| [configure_passwordless_ssh.yml](./configure_passwordless_ssh.md) | Sets up password-less SSH trust between all hosts. | | +| [convert_ansible_inventory.sh](./convert_ansible_inventory.sh.md) | Converts nonstandard Ansible inventories to clustered format | Script | +| [create_instance.yml](./create_instance.md) | Top-level orchestrator: bootstraps all infra, Oracle Linux Automation Manager, teardown. | Most plays/templates | +| [default_vars.yml](./default_vars.md) | All central configuration: VM sizing, features, credentials. | | +| [deploy_olam_cluster.yml](./deploy_olam_cluster.md) | Multi-node Oracle Linux Automation Manager cluster install (control/execution/db nodes). | | +| [deploy_olam_none.yml](./deploy_olam_none.md)| No-op for conditional disables or dry-runs. | | +| [deploy_olam_olae.yml](./deploy_olam_olae.md) | Installs ansible-core for basic OLAE only test/dev setups. | | +| [deploy_olam_single.yml](./deploy_olam_single.md) | Single-control-node Oracle Linux Automation Manager deployment for quickstart/testing. | | +| [deploy_olam_v1.yml](./deploy_olam_v1.md) | Deploys legacy (v1) Oracle Linux Automation Manager for migration/compatibility. | | +| [get_facts.yml](./get_facts.md) | Minimal fact gathering utility, prints localhost info. | | +| [provision_builder.yml](./provision_builder.md) | Builds custom Ansible Builder Execution Environments (EE) | execution_environment.yml.j2, requirements.yml.j2, requirements.txt.j2, bindep.txt.j2, playbook.yml.j2 | +| [provision_free_ipa.yml](./provision_free_ipa.md) | Sets up FreeIPA for SSO/directory integration via role. | install_ipa.j2 | +| [provision_git_server.yml](./provision_git_server.md) | Bootstraps a git server and creates initial repo. | | +| [provision_instance_basics.yml](./provision_instance_basics.md) | Ensures all base users, SSH, tags, and locales are ready. | | +| [provision_kvm.yml](./provision_kvm.md) | Installs KVM/libvirt/cockpit for in-lab virtualization. | | +| [provision_pah.yml](./provision_pah.md) | Sets up Private Automation Hub (PAH) for collection sharing. | hosts.j2 | +| [provision_vnc.yml](./provision_vnc.md) | Installs VNC/GUI on devops-node(s) for remote graphical login. | | +| [requirements.yml](./requirements.md) | Lists all Ansible Galaxy collection requirements. | | +| [terminate_instance.yml](./terminate_instance.md) | Deletes OCI lab VMs/resources and prompts for artifact wipe. | | +| [update_all_rpms.yml](./update_all_rpms.md) | Updates all packages, reboots lab hosts as needed. | | + +### Templates – Index + +| Template | Description & Usage | +| --- | --- | +| [bindep.txt.j2](./templates/bindep.txt.j2.md) | Build/package dependencies for Execution Environments | +| [egress_security_rules.j2](./templates/egress_security_rules.j2.md) | OCI security rule: enables all TCP egress | +| [execution_environment.yml.j2](./templates/execution_environment.yml.j2.md) | Ansible Builder EE build context/deps | +| [hosts.j2](./templates/hosts.j2.md) | Ansible inventory for PAH/single-host setups | +| [ingress_security_rules.j2](./templates/ingress_security_rules.j2.md) | Dynamic ingress rules for OCI security—feature toggled | +| [install_ipa.j2](./templates/install_ipa.j2.md) | Shell install script for FreeIPA server | +| [nginx.conf.j2](./templates/nginx.conf.j2.md) / [nginx.conf_v1.j2](./templates/nginx.conf_v1.j2.md) | Base Nginx config, feature toggled server blocks | +| [oci_vars.j2](./templates/oci_vars.j2.md) | Core OCID variables for templates and automation | +| [playbook.yml.j2](./templates/playbook.yml.j2.md) | Sample EE task playbook: gets OCI storage namespace | +| [receptor_cluster.conf.j2](./templates/receptor_cluster.conf.j2.md) | Config for multi-node receptor mesh (lab HA/cluster) | +| [receptor.conf.j2](./templates/receptor.conf.j2.md) | Single node receptor config, group logic | +| [requirements.txt.j2](./templates/requirements.txt.j2.md) | Python (pip) requirements for EEs | +| [requirements.yml.j2](./templates/requirements.yml.j2.md) | Galaxy collection requirements for EEs | + +--- + +## Tree Listing + +```markdown +└── olam +    ├── block.md +    ├── build.md +    ├── check_instance_available.md +    ├── configure_passwordless_ssh.md +    ├── convert_ansible_inventory.sh.md +    ├── create_instance.md +    ├── default_vars.md +    ├── deploy_olam_cluster.md +    ├── deploy_olam_none.md +    ├── deploy_olam_olae.md +    ├── deploy_olam_single.md +    ├── deploy_olam_v1.md +    ├── get_facts.md +    ├── provision_builder.md +    ├── provision_free_ipa.md +    ├── provision_git_server.md +    ├── provision_instance_basics.md +    ├── provision_kvm.md +    ├── provision_pah.md +    ├── provision_vnc.md +    ├── README.md +    ├── requirements.md +    ├── terminate_instance.md +    ├── update_all_rpms.md +   └── templates +       ├── bindep.txt.j2.md +       ├── egress_security_rules.j2.md +       ├── execution_environment.yml.j2.md +       ├── hosts.j2.md +       ├── ingress_security_rules.j2.md +       ├── install_ipa.j2.md +       ├── nginx.conf_v1.j2.md +       ├── nginx.conf.j2.md +       ├── oci_vars.j2.md +       ├── playbook.yml.j2.md +       ├── receptor_cluster.conf.j2.md +       ├── receptor.conf.j2.md +       ├── requirements.txt.j2.md +       └── requirements.yml.j2.md +``` + +--- + +## Relationships and Workflow + +- **create_instance.yml** is the main entrypoint—manages inventory, infra, VMs, all feature provisioning, and teardown. +- **block.yml** and **build.yml** manage granular host, storage, and resource setup. +- **provision_builder.yml**, **provision_git_server.yml**, **provision_free_ipa.yml**, **provision_pah.yml** bring up the full auxiliary stack for complete enterprise-style labs. +- **configure_passwordless_ssh.yml** and **provision_instance_basics.yml** must run early to ensure all hosts are ready to receive further automation. +- All templates can be mapped to their consuming playbooks above—see individual .md docs for specifics and downstream usage. + +--- + +## Tips and Best Practices + +- Review each individual Markdown doc for file-specific details, usage notes, and in-context examples. +- Always use version-pinned dependency management via `requirements.yml`. +- Keep code and docs in sync: update the corresponding `.md` file for any playbook, role, or template change. + +--- + +## References + +- [Oracle Cloud Infrastructure Documentation](https://docs.oracle.com/en-us/iaas/Content/home.htm) +- [OCI Ansible Collection](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/) +- [Oracle Linux Automation Manager](https://docs.oracle.com/en/operating-systems/oracle-linux-automation-manager/) + +--- + +For troubleshooting, edge use cases, or advanced onboarding, see individual `.md` files in this directory. diff --git a/olam/docs/block.md b/olam/docs/block.md new file mode 100644 index 0000000..7a6f010 --- /dev/null +++ b/olam/docs/block.md @@ -0,0 +1,35 @@ +# block.yml Documentation + +## Purpose & Overview + +Provisions and attaches one or more OCI block storage volumes to a target compute instance, using Ansible's cloud modules for robust, repeatable storage automation. + +## When to Use + +Use as part of an automation workflow where instances require custom or expanded storage, for shared data, persistent application state, or advanced IO benchmarking. + +## Key Variables & Inputs + +- `add_block_storage`: Boolean, drives whether to provision blocks. +- `my_compartment_id`, `my_availability_domain`: OCI references. +- `item.value.instance_name`, `timestamp`: Used to generate unique volume names. +- `block_volume_size_in_gbs`: Size of each block. +- `my_instance_id`: Target for attachment. +- `block_devices`: List of disk suffixes (e.g., [b, c, d]) for device names. +- `ansible_loop.index0`: Index for naming/mounting. + +## Task Breakdown + +- Creates a uniquely named OCI block storage volume for each required device. +- Sets a fact for volume_id for downstream reference. +- Attaches each block to the compute instance (as paravirtualized). +- All steps are robustly guarded with retries and fail handling. + +## Dependencies & Relationships + +- Typically included by main provisioning playbooks (build.yml, create_instance.yml). +- Uses OCI config/profile variables for secure connection. +- Requires a running compute instance and OCI Ansible collection. +- Variable block_devices tied to the number and order of disks per host. + +## Output/Result diff --git a/olam/docs/build.md b/olam/docs/build.md new file mode 100644 index 0000000..8f51907 --- /dev/null +++ b/olam/docs/build.md @@ -0,0 +1,33 @@ +# build.yml Documentation + +## Purpose & Overview + +Automates the creation of an OCI compute instance with robust network, storage, and VNIC configuration for Oracle Linux Automation Manager/Oracle Linux Automation Manager labs. + +## When to Use + +Run during lab provisioning to instantiate VMs with cloud-agnostic bootstrapping, public/private IP allocation, and storage attachment. + +## Key Variables & Inputs + +- `my_availability_domain`, `my_compartment_id`, `ol_image_id`, `instance_shape`, `instance_ocpus`, `instance_memory`, `my_subnet_id`, `private_key`. +- References from default_vars.yml and cumulative variables from parent tasks. +- `block_count`/`block_devices` for volume attachment. + +## Task Breakdown + +- Provisions an OCI compute instance, specifying source image and boot volume size. +- Sets authorized SSH key, agent, and monitoring options. +- Fetches and sets up VNICs for public/private IP mapping. +- Registers and maintains instance display_name and instance_id. +- Includes tasks from block.yml to dynamically attach storage. +- Adds hosts to both Ansible's dynamic inventory and hosts file for integration with follow-up playbooks. +- Optionally prints instance connection info for debugging or tracking. + +## Dependencies & Relationships + +- Must be called with valid OCI and SSH configuration in-place. +- Calls block.yml for storage extension. +- Linked via parent orchestrator to overall lab creation/teardown logic. + +## Output/Result diff --git a/olam/docs/check_instance_available.md b/olam/docs/check_instance_available.md new file mode 100644 index 0000000..bab170e --- /dev/null +++ b/olam/docs/check_instance_available.md @@ -0,0 +1,28 @@ +# check_instance_available.yml Documentation + +## Purpose & Overview + +Checks that newly created lab or cloud instances are accessible via Ansible, performs minimal fact gathering, and prints inventory/state for debugging and workflow readiness. + +## When to Use + +Run after provisioning or deploying compute/network infrastructure to confirm all hosts are online and accessible to Ansible for further setup or automation. + +## Key Variables & Inputs + +- Hosts: all:!localhost +- Variables: debug_enabled for optional debugging. +- Includes: default_vars.yml, oci_vars.yml. + +## Task Breakdown + +- Waits for SSH/Ansible connection readiness for each instance. +- Gathers Ansible facts for each host. +- Prints out in-memory inventory and all facts per host (optional, for debugging/troubleshooting). + +## Dependencies & Relationships + +- Should be run after playbooks that create or modify host infrastructure (e.g., create_instance.yml). +- Facts are required for downstream configuration tasks (user, SSH, etc). + +## Output/Result diff --git a/olam/docs/configure_passwordless_ssh.md b/olam/docs/configure_passwordless_ssh.md new file mode 100644 index 0000000..4056012 --- /dev/null +++ b/olam/docs/configure_passwordless_ssh.md @@ -0,0 +1,31 @@ +# configure_passwordless_ssh.yml Documentation + +## Purpose & Overview + +Automatically establishes password-less SSH access between all lab hosts (excluding localhost and "remote") by generating SSH key pairs, exchanging and installing public keys, and pre-populating known_hosts to avoid SSH prompts. + +## When to Use + +Run anytime after instantiation or when machine/user trust is needed for seamless automation, job dispatch, or inter-node orchestration. + +## Key Variables & Inputs + +- `username`: User to receive and use generated keys. +- `private_key`: SSH private key basename (default: id_rsa). +- `ansible_play_hosts_all`: Dynamic host list; excludes "localhost". +- `my_subnet_domain_name`: Used for accurate inventory/trust. +- debug_enabled: Prints out hostvars for host state checks. + +## Task Breakdown + +- Generates SSH keypair for target user. +- Fetches and gathers all host public keys. +- Loops through hosts to update authorized_keys and populate known_hosts. +- Trusted host connectivity for all remaining workflow steps. + +## Dependencies & Relationships + +- Requires SSH access to all hosts. +- Downstream dependency for automation modules that require agentless, password-less connections (Ansible, scp, rsync, etc). + +## Output/Result diff --git a/olam/docs/convert_ansible_inventory.sh.md b/olam/docs/convert_ansible_inventory.sh.md new file mode 100644 index 0000000..990eebf --- /dev/null +++ b/olam/docs/convert_ansible_inventory.sh.md @@ -0,0 +1,25 @@ +# convert_ansible_inventory.sh Documentation + +## Purpose & Overview +Bash shell script to convert a legacy or ad-hoc Ansible inventory file into a clustered, group-organized inventory format suitable for OLAM hybrid/cluster/topology use. + +## When to Use +Use when migrating inventory files for new automation team members, onboarding multi-group labs (control, execution, hop, db), or standardizing disparate or hand-edited inventory lists. + +## Key Inputs & Usage +- Takes a single argument: the inventory input file to convert (plain text) +- Outputs results to stdout (redirect or copy/paste output for use as new inventory) + +## Script Breakdown +- Validates argument/input state and file existence. +- Processes input line-by-line to separate out control, execution, and other logical groups. +- Strips SSH connection settings for cleaner output. +- Emits per-group sections, with variables and peers set for clustering. +- Produces [all:vars] block for global user/SSH configuration. + +## Dependencies & Relationships +- Consumed by onboarding, migration, or pipeline/init steps in OLAM labs. +- Called outside Ansible (CLI), but output is directly consumed as lab inventory. + +## Output/Result +- Reusable, group-wise inventory file ready for Ansible playbooks or pipeline/distributed automation. diff --git a/olam/docs/create_instance.md b/olam/docs/create_instance.md new file mode 100644 index 0000000..a512760 --- /dev/null +++ b/olam/docs/create_instance.md @@ -0,0 +1,31 @@ +# create_instance.yml Documentation + +## Purpose & Overview + +Top-level playbook for full-lifecycle lab provisioning and teardown—including compute, networking, security rules, and Oracle Linux Automation Manager stack (installer, builder, PAH, FreeIPA, Git, etc.). + +## When to Use + +Use to launch environments for development, QA, or training with Oracle Linux Automation Manager, Ansible AWX, and supporting tools in a self-contained, repeatable way. + +## Key Variables & Inputs + +- See default_vars.yml for: compute_instances, base images, SSH/user, toggles for OLAM/PAH/FreeIPA/Git/KVM/VNC/etc. +- OCI config and cloud variables from facts and included var files. +- State file (.ansible-state) used for tracking resource OCIDs. + +## Task Breakdown + +- Gathers facts and creates all OCI infrastructure: VCN, subnet, gateways, route tables, security lists, instances. +- Builds hosts and configures inventory, SSH, and facts (build.yml, block.yml). +- Sets up base users and agentless automation via host configuration playbooks. +- Delegates installer/finalization flows for Oracle Linux Automation Manager cluster, builder, PAH, FreeIPA, Git, KVM, VNC based on feature flags. +- Ensures end-to-end readiness of all core and optional services. +- Teardown handled via terminate_instance.yml, removes all artifacts. + +## Dependencies & Relationships + +- Central orchestrator: calls/integrates every major automation playbook/template in olam/. +- Requires all key variables and inventory correct in advance. + +## Output/Result diff --git a/olam/docs/default_vars.md b/olam/docs/default_vars.md new file mode 100644 index 0000000..c14de8a --- /dev/null +++ b/olam/docs/default_vars.md @@ -0,0 +1,32 @@ +# default_vars.yml Documentation + +## Purpose & Overview + +Central variable definition file for Oracle Linux Automation Manager (OLAM) labs: describes hosts, images, instance types/volume sizes, credentials, toggles for all feature components (VNC, builder, PAH, FreeIPA, Git, etc.), and configuration for advanced cases (KVM, VNC, root, etc.). + +## When to Use + +Always included as a vars_files entry in parent playbooks; edit or override for lab customization, QA, demo, or training scenarios. + +## Key Variables & Inputs + +- `compute_instances`: Host inventory and configs +- `os`, `os_version`: Kernel image selection +- `instance_shape`, `instance_ocpus`, `instance_memory`, `boot_volume_size_in_gbs` +- All toggles: `use_*` for PAH, builder, FreeIPA, Git, KVM, VNC, password-less_ssh, and more +- Cloud and KVM image URLs and hashes +- Credentials for Oracle Linux Automation Manager/Ansible, AWX admin, database, etc. +- Network/domain/proxy variables and sample proxy_env and pip_proxy_env + +## Task Breakdown + +- Exported as a variable file to any play needing resource or deployment context. +- Models all required settings for building, configuring, and tearing down complete Oracle Linux Automation Manager, builder, and DevOps environments. +- All secrets/example passwords can be overridden at runtime. + +## Dependencies & Relationships + +- Read by every major playbook in olam/. +- Directly referenced by most templates in the lab for runtime dictionary lookups. + +## Output/Result diff --git a/olam/docs/deploy_olam_cluster.md b/olam/docs/deploy_olam_cluster.md new file mode 100644 index 0000000..b32dc2d --- /dev/null +++ b/olam/docs/deploy_olam_cluster.md @@ -0,0 +1,35 @@ +# deploy_olam_cluster.yml Documentation + +## Purpose & Overview + +Deploys a highly available, multi-host Oracle Linux Automation Manager (OLAM) cluster, building all control/execution/database components, configuring required repos, postgresql DB, firewall rules, Automation Manager, Nginx, receptors, AWX peering, and optional secrets/certs. + +## When to Use + +Run when building out an HA (control + execution + DB) test, QA, or training environment for advanced testing or simulation of real-world Oracle Linux Automation Manager production setups. + +## Key Variables & Inputs + +- Host inventory: control, execution, db groups. +- default_vars.yml for user/SSH, images, and feature toggles. +- Proxy, pip/proxy_env for external access. +- User, DB, credential variables for AWX/Oracle Linux Automation Manager. + +## Task Breakdown + +- Installs and configures package repos and dependencies (EPEL, psycopg2, OpenSSL, pip, etc). +- Handles version-locking and Python requirements per OL. +- Installs and configures PostgreSQL on DB node, creates users, sets config and port. +- Configures Automation Manager on control/execution. +- Creates ansible project directories, inventory, and config files (nginx, receptor, etc.). +- Runs podman image builds as needed. +- Handles lingering, services, and firewalld for container and automation ports. +- Runs the full Oracle Linux Automation Manager/Automation Manager suite and sets up cluster links. + +## Dependencies & Relationships + +- Consumes default_vars.yml for nearly all setup. +- References/uses inventory, hosts, group_vars, and integrates with all primary Oracle Linux Automation Manager templates. +- Peers AWX nodes, routers, DB, and configures container execution environments. + +## Output/Result diff --git a/olam/docs/deploy_olam_none.md b/olam/docs/deploy_olam_none.md new file mode 100644 index 0000000..cf4f897 --- /dev/null +++ b/olam/docs/deploy_olam_none.md @@ -0,0 +1,25 @@ +# deploy_olam_none.yml Documentation + +## Purpose & Overview + +A “no operation” (noop) playbook for Oracle Linux Automation Manager. Used to satisfy workflow requirements when cluster deployment or setup is intentionally skipped. + +## When to Use + +Serve as a placeholder for tasks, demo, or CI flows that want to disable Oracle Linux Automation Manager deploy logic without breaking dependency chains. + +## Key Variables & Inputs + +- None; runs on hosts in the control group. + +## Task Breakdown + +- Prints a message to the log stating that this is a noop and Oracle Linux Automation Manager is not being deployed. + +## Dependencies & Relationships + +- Used by create_instance.yml and as an import/inclusion target when skipping Oracle Linux Automation Manager deploy or install logic in conditionals. + +## Output/Result + +- No changes made; simply logs intention for auditing/clarity in automation output. diff --git a/olam/docs/deploy_olam_olae.md b/olam/docs/deploy_olam_olae.md new file mode 100644 index 0000000..f1c1d43 --- /dev/null +++ b/olam/docs/deploy_olam_olae.md @@ -0,0 +1,24 @@ +# deploy_olam_olae.yml Documentation + +## Purpose & Overview + +Installs the core "ansible-core" package on Oracle Linux Automation Manager control nodes using dnf/yum, preparing the system for Oracle Linux Automation Engine (OLAE) workloads. + +## When to Use +Use for standalone Oracle Linux Automation Engine deployments, baseline lab environments, or developer/test setups that require only Ansible Engine (not the full Oracle Linux Automation Manager suite). + +## Key Variables & Inputs + +- Hosts: control group +- default_vars.yml included + +## Task Breakdown + +- Installs ansible-core from OS repositories, with retry/delay for robustness. + +## Dependencies & Relationships + +- Can be included as an import in create_instance.yml, or run as a standalone Oracle Linux Automation Engine preparation. +- Required as a base step for any Oracle Linux Automation Engine environment where lab automation is desired. + +## Output/Result diff --git a/olam/docs/deploy_olam_single.md b/olam/docs/deploy_olam_single.md new file mode 100644 index 0000000..fba0b07 --- /dev/null +++ b/olam/docs/deploy_olam_single.md @@ -0,0 +1,31 @@ +# deploy_olam_single.yml Documentation + +## Purpose & Overview + +Automates the full deployment of a single-node Oracle Linux Automation Manager (OLAM) instance, including all dependencies, PostgreSQL database, Nginx, certificates, firewall, and enabling all required services. + +## When to Use + +Use for test/dev setups or demos where a highly available multi-node cluster is unnecessary; enables Oracle Linux Automation Manager on a single host for rapid evaluation, training, or integration. + +## Key Variables & Inputs + +- Inventory group: control +- Variables for DB host, AWX instance, user/password configuration from default_vars.yml +- All OS, image, and package info dynamically mapped from facts or configuration. + +## Task Breakdown + +- Installs required EPEL repos, manages package version locks. +- Sets up Python and pip dependencies for Ansible/AWX/DB. +- Bootstraps PostgreSQL for underlying automation platform storage. +- Downloads and installs the right Oracle Linux Automation Manager version/repo, then enables services. +- Prepares Nginx and Receptor configs, issues SSL certificates, and manages firewalld for required ports. +- Configures all necessary systemd service units and admin credentials. + +## Dependencies & Relationships + +- Used by create_instance.yml/imported in lab resets or testbed creation. +- Downstream items: integrates with all Inventory/host roles, receives facts from variable files, and feeds other test automation. + +## Output/Result diff --git a/olam/docs/deploy_olam_v1.md b/olam/docs/deploy_olam_v1.md new file mode 100644 index 0000000..a65a512 --- /dev/null +++ b/olam/docs/deploy_olam_v1.md @@ -0,0 +1,30 @@ +# deploy_olam_v1.yml Documentation + +## Purpose & Overview + +Installs Oracle Linux Automation Manager (OLAM) version 1.0 for single-node legacy setups, including all platform dependencies, database (PostgreSQL), Nginx, certificates, firewall/services, and basic facts setup. + +## When to Use + +Use for compatibility, migration, or demo environments where the original Oracle Linux Automation Manager stack (pre-2.x) is required—either for existing asset support or validation. + +## Key Variables & Inputs + +- Inventory group: control +- Variables and image URLs from default_vars.yml +- Service toggles, DB/PKI/Nginx setup variables + +## Task Breakdown + +- EPEL, pip, and version lock setup +- Oracle Linux Automation Manager 1.0 repo enable; disables other Oracle Linux Automation Manager repositories +- Bootstraps and configures local PostgreSQL backend +- AWX admin/user DB, service/host config, and PKI/cert generation +- Installs/starts Oracle Linux Automation Manager, required firewall ports, cluster ID config, and Nginx + +## Dependencies & Relationships + +- Requires correct host group and OL base image +- Sets up all database, control, and service infrastructure for AWX/Oracle Linux Automation Manager v1 + +## Output/Result diff --git a/olam/docs/get_facts.md b/olam/docs/get_facts.md new file mode 100644 index 0000000..e45b399 --- /dev/null +++ b/olam/docs/get_facts.md @@ -0,0 +1,25 @@ +# get_facts.yml Documentation + +## Purpose & Overview + +Collects minimal Ansible facts about the localhost. Prints basic host/system info for use in automation validation, debugging, or pre-flight checks. + +## When to Use + +Run when you want to verify ansible’s local environment, test minimal connectivity, or provide a fact base for lab or CI/CD runs. + +## Key Variables & Inputs + +- Hosts: localhost + +## Task Breakdown + +- Uses Ansible’s setup module with "min" gather_subset to collect only necessary system attributes. +- Prints both the gathered facts and current date for status tracking or log auditing. + +## Dependencies & Relationships + +- Standalone/supporting playbook, not dependent on any global configuration files or host groupings. +- Can be called as a utility by other provisioning or state-validation workflows. + +## Output/Result diff --git a/olam/docs/provision_builder.md b/olam/docs/provision_builder.md new file mode 100644 index 0000000..265882a --- /dev/null +++ b/olam/docs/provision_builder.md @@ -0,0 +1,31 @@ +# provision_builder.yml Documentation + +## Purpose & Overview + +Automates the setup of an Ansible Builder development node for Oracle Linux Automation Manager/AWX environments—prepares Execution Environments, required dependencies, and builds custom container images for automation jobs. + +## When to Use + +Run when creating or updating container-based execution environments (EEs) for Oracle Linux Automation Manager, especially when customizing requirements, dependencies, or base configs for advanced automation workflows. + +## Key Variables & Inputs + +- Hosts: devops-node +- Includes default_vars.yml for user and path setup + +## Task Breakdown + +- Installs and enables Automation Manager repos, disables old versions +- Ensures lingering and service persistence for the user account +- Installs ansible-builder, ansible-navigator, pip/py +- Creates all required EE project files: execution_environment.yml, ansible.cfg, requirements.yml, requirements.txt, bindep.txt +- Builds EE container using ansible-builder +- Creates a project directory and sample playbook for manual or automated EE testing +- Handles all OS variations, permissions, and enables debug diagnostics + +## Dependencies & Relationships + +- Consumed by OLAM devops nodes, typically from create_instance.yml or as a post-provision step for advanced automation +- Uses multiple templates for EE construction (execution_environment.yml.j2, requirements.yml.j2, bindep.txt.j2, requirements.txt.j2, playbook.yml.j2) + +## Output/Result diff --git a/olam/docs/provision_free_ipa.md b/olam/docs/provision_free_ipa.md new file mode 100644 index 0000000..c72eb75 --- /dev/null +++ b/olam/docs/provision_free_ipa.md @@ -0,0 +1,27 @@ +# provision_free_ipa.yml Documentation + +## Purpose & Overview + +Deploys and configures a FreeIPA server for centralized authentication and identity management as part of an Oracle Linux Automation Manager lab or testbed. + +## When to Use + +Run to enable Kerberos-based SSO, directory, or DNS support for instances in testing/training environments. + +## Key Variables & Inputs + +- Hosts: ipa-server +- ipaserver_domain, ipaserver_realm, ipaadmin_password, ipadm_password + +## Task Breakdown + +- Calls freeipa.ansible_freeipa.ipaserver Ansible role for full FreeIPA install (recommended path for Oracle Linux Automation Manager/Ansible lab setups) +- Variables set to align with facts and lab domain environment. + +## Dependencies & Relationships + +- Requires the freeipa.ansible_freeipa Galaxy role/collection. +- Integrated into overall lab via inventory/host groups ("ipa-server"). +- Downstream effect for host setup, authentication, and seamless SSO. + +## Output/Result diff --git a/olam/docs/provision_git_server.md b/olam/docs/provision_git_server.md new file mode 100644 index 0000000..bde8e44 --- /dev/null +++ b/olam/docs/provision_git_server.md @@ -0,0 +1,29 @@ +# provision_git_server.yml Documentation + +## Purpose & Overview + +Fully automates the setup of a basic Git server for lab/CI testing, ensuring the presence of a “git” user, SSH key management, bare repo initialization, and default branch configuration. + +## When to Use + +Use to enable version control, CI/CD, or repo hosting within a self-contained OLAM lab; ideal for demonstrating GitOps or onboarding new users to Git-centric workflows in labs or sandboxes. + +## Key Variables & Inputs + +- Hosts: git-server +- `ssh_key_params`, `private_key`, all credential inputs for the git user + +## Task Breakdown + +- Adds “git” user and authorizes SSH key for secure access +- Installs git with retries for idempotency +- Creates initial bare repository at the fixed path (hello-world.git) +- Sets default branch to “main” +- Initializes/creates repo with git, supporting push/pull semantics for lab team + +## Dependencies & Relationships + +- Assumes git-server host group, must be present and accessible +- SSH key must be provisioned and present for secure auth by clients + +## Output/Result diff --git a/olam/docs/provision_instance_basics.md b/olam/docs/provision_instance_basics.md new file mode 100644 index 0000000..4ad7ed4 --- /dev/null +++ b/olam/docs/provision_instance_basics.md @@ -0,0 +1,30 @@ +# provision_instance_basics.yml Documentation + +## Purpose & Overview + +Prepares newly provisioned instances in the Oracle Linux Automation Manager/ lab for further automation: grows the root filesystem, configures user with password-less sudo and SSH, creates required directories, and ensures proper locale and firewall settings. + +## When to Use + +Use as one of the first steps after bringing instances online via automation, to guarantee all hosts are ready for subsequent roles/playbooks. + +## Key Variables & Inputs + +- Hosts: all:!localhost:!remote +- Variables: username, user_default_password, private_key, debug_enabled + +## Task Breakdown + +- Grows root filesystem using oci-growfs. +- Adds (or confirms) the primary Ansible user, ensures inclusion in sudoers/wheel, and enables password-less sudo. +- Sets up authorized ssh key for secure, agentless automation. +- Creates required directories for Ansible temp data. +- Appends locale settings to .bashrc for shell and downstream process compatibility. +- Optionally logs firewalld rejections to the system journal for diagnostic or troubleshooting needs. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and invoked for all provisioned lab hosts. +- Reads default_vars.yml and oci_vars.yml for configuration. + +## Output/Result diff --git a/olam/docs/provision_kvm.md b/olam/docs/provision_kvm.md new file mode 100644 index 0000000..8535ee3 --- /dev/null +++ b/olam/docs/provision_kvm.md @@ -0,0 +1,29 @@ +# provision_kvm.yml Documentation + +## Purpose & Overview + +Automates installation/configuration of a KVM (libvirt/QEMU) hypervisor on a dedicated `kvm-server` laboratory node in Oracle Linux Automation Manager labs, handling service, group, and firewall settings. + +## When to Use + +Run to bootstrap a testbed hypervisor for VM lab/dev clusters when Oracle Linux 8/9 is used as the OS platform. + +## Key Variables & Inputs + +- Hosts: kvm-server +- All package names are conditional on OS major version. +- `username` (for group membership, authority) + +## Task Breakdown + +- Installs `@virt` group plus tooling for virtualization, containerization, and cockpit management on OL8; modular packages for OL9. +- Enables and starts required libvirt and cockpit services/sockets. +- Opens firewall ports for libvirt access. +- Adds user to libvirt/qemu groups for non-root virtualization and resets SSH. + +## Dependencies & Relationships + +- May be called by create_instance.yml (as an import) or on-demand for base hypervisor role install. +- VM creation and testing must follow, using a compatible KVM playbook or tool. + +## Output/Result diff --git a/olam/docs/provision_pah.md b/olam/docs/provision_pah.md new file mode 100644 index 0000000..8eeab85 --- /dev/null +++ b/olam/docs/provision_pah.md @@ -0,0 +1,28 @@ +# provision_pah.yml Documentation + +## Purpose & Overview + +Deploys and configures Oracle Linux Private Automation Hub (PAH) on a dedicated host for managing collections, content, and roles in Oracle Linux Automation Manager lab and hybrid infrastructures. + +## When to Use + +Run to enable a lab-internal automation hub for distributing approved or custom content, especially when working in teams or disconnected environments. + +## Key Variables & Inputs + +- Hosts: ol-pah +- OS version detection, user/group variables for PAH inventory/ownership. + +## Task Breakdown + +- Installs/corrects EPEL, disables obsolete repositories, enables Oracle Linux Automation Manager PAH repo. +- Installs PAH installer, copies playbooks and templated inventory (hosts.j2), and runs single-node installation. +- Sets up ansible environment files (single_node), does everything with correct user ownership and permission. +- Runs final PAH installer playbook using ansible, printing results for diagnostics. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and devops/project-level topology. +- Requires a host named "ol-pah" and user credential handling. + +## Output/Result diff --git a/olam/docs/provision_vnc.md b/olam/docs/provision_vnc.md new file mode 100644 index 0000000..029164f --- /dev/null +++ b/olam/docs/provision_vnc.md @@ -0,0 +1,29 @@ +# provision_vnc.yml Documentation + +## Purpose & Overview + +Installs and configures TigerVNC server and GNOME desktop for lab/dev automation hosts, enabling remote graphical logins for CLI alternative, UI tests, or onboarding. + +## When to Use + +Run on devops-node or as part of full-lab automation to provide GUI access for demos, debugging, or student/QA use. + +## Key Variables & Inputs + +- Hosts: devops-node +- `vnc_port`, `vnc_default_password`, `username`, `usergroup`, `vnc_geometry` + +## Task Breakdown + +- Installs GUI and VNC components. +- Sets system to default to graphical login. +- Creates the user's .vnc directory and password file with secure permissions. +- Configures session geometry, assigns username to port, and sets up systemd VNC service. +- Auth/ownership/permissions configured per-user for secure multi-user access. + +## Dependencies & Relationships + +- Runs after initial host configuration (host_setup, provision_instance_basics). +- Used by devops teams for remote lab access. + +## Output/Result diff --git a/olam/docs/requirements.md b/olam/docs/requirements.md new file mode 100644 index 0000000..c7a76c8 --- /dev/null +++ b/olam/docs/requirements.md @@ -0,0 +1,33 @@ +# requirements.yml Documentation + +## Purpose & Overview + +Specifies all required Ansible Galaxy collections to support the Oracle Linux Automation Manager/ lab automation and infrastructure playbooks. Ensures all playbooks, roles, and modules have compatible and tested dependencies. + +## When to Use + +Run before executing any playbook by installing all listed collections: + +```bash +ansible-galaxy collection install -r requirements.yml +``` + +This guarantees that your lab automation will not fail due to missing dependencies. + +## Collections Listed + +- `ansible.posix` +- `community.general` +- `community.postgresql` +- `community.crypto` (locked to ">=2.26.0,<2.26.99") +- `freeipa.ansible_freeipa` +- `community.libvirt` +- `oracle.oci` +- `ovirt.ovirt` +- `containers.podman` + +## Dependencies & Relationships + +- All playbooks and tasks in Oracle Linux Automation Manager/ depend on these collections for cloud, VM, DB, identity, container, and core automation. + +## Output/Result diff --git a/olam/docs/templates/bindep.txt.j2.md b/olam/docs/templates/bindep.txt.j2.md new file mode 100644 index 0000000..1d1da26 --- /dev/null +++ b/olam/docs/templates/bindep.txt.j2.md @@ -0,0 +1,26 @@ +# bindep.txt.j2 Documentation + +## Purpose & Overview + +Jinja2 template for Ansible Builder and Oracle Linux Automation Manager lab automation projects—provides required system packages for container image builds (Execution Environments). + +## When to Use + +Used during container/EE builds; ensures all extension dependencies for ansible modules, pip, or external tools are pre-installed on OL8/OL9 labs. + +## Key Variables & Inputs + +- Distribution detection (major version) controls whether python3-devel or python3.11-devel is included. + +## Task Breakdown + +- Conditional Jinja2 templating: adds different python-devel packages for OL8 vs OL9 for max compatibility. +- Lists OSS/C/SSL/XML libraries crucial for many collections/modules. + +## Dependencies & Relationships + +- Called from builder pipelines, playbooks, or roles that need container/system-level package lists. + +## Output/Result + +- bindep.txt included in EE or container build ensures smooth, error-free playbook/module installation. diff --git a/olam/docs/templates/egress_security_rules.j2.md b/olam/docs/templates/egress_security_rules.j2.md new file mode 100644 index 0000000..513bd48 --- /dev/null +++ b/olam/docs/templates/egress_security_rules.j2.md @@ -0,0 +1,28 @@ +# egress_security_rules.j2 Documentation + +## Purpose & Overview + +YAML/Jinja2 template for OCI instance security lists, allowing unrestricted TCP egress from all lab hosts (“allow all” rule). + +## When to Use + +Include wherever automated security policy/gen is needed for outbound network access (e.g., VMs, proxy, or automation endpoints in lab). + +## Key Variables & Inputs + +- Static—no variables or dynamic logic. +- Exposes `instance_egress_security_rules` as a list (all TCP traffic to any destination). + +## Task Breakdown + +- Standardizes “allow all” lab egress in security list YAML files. +- Used in automation for hands-on, demo, or multi-node labs. + +## Dependencies & Relationships + +- Primarily included or imported by main lab provisioning workflows. +- Should be cross-linked to ingress_security_rules.j2 for full OCI policy config. + +## Output/Result + +- Hosts will be granted unrestricted TCP egress during provisioning. diff --git a/olam/docs/templates/execution_environment.yml.j2.md b/olam/docs/templates/execution_environment.yml.j2.md new file mode 100644 index 0000000..1ddfa72 --- /dev/null +++ b/olam/docs/templates/execution_environment.yml.j2.md @@ -0,0 +1,29 @@ +# execution_environment.yml.j2 Documentation + +## Purpose & Overview + +Jinja2 template for building custom Execution Environment (EE) container images for AWX/Oracle Linux Automation Manager with Ansible Builder. Specifies all dependencies and base image logic required for repeatable, production-grade container automation. + +## When to Use + +File is rendered whenever building a new or updated EE container for Oracle Linux Automation Manager labs—ensuring module, pip, and OS/package dependencies are met. + +## Key Variables & Inputs + +- Distribution major version (OL8/OL9) chooses correct base image. +- Requires requirements.yml, requirements.txt, bindep.txt as dependency files. + +## Task Breakdown + +- Template logic sets up pip, system, and galaxy dependency lists. +- Selects correct EE image from Oracle Container Registry, prepping for builder pulls. +- Provides custom pre and post build steps for image labeling, shell debugging, and extension. + +## Dependencies & Relationships + +- Consumed by provision_builder.yml whenever building EEs. +- Works with all supporting dependency files and ansible.cfg. + +## Output/Result + +- Defines a versioned, dependency-aware EE container image—critical for AWX/Oracle Linux Automation Manager automation and modern CI/CD labs. diff --git a/olam/docs/templates/hosts.j2.md b/olam/docs/templates/hosts.j2.md new file mode 100644 index 0000000..f4f55f9 --- /dev/null +++ b/olam/docs/templates/hosts.j2.md @@ -0,0 +1,23 @@ +# hosts.j2 Documentation + +## Purpose & Overview +Template for a minimal Ansible inventory in YAML format for OLAM labs (PAH/Automation Hub). Maps the "hub" host (the PAH) and assigns user credentials. + +## When to Use +Render this template when creating inventory for PAH-related plays, automation runs, or as a base inventory for lab/demo development. + +## Key Variables & Inputs + +- hub: the target node for collection sharing, admin, or lab orchestration (ol-pah, user oracle). + +## Task Breakdown + +- Outputs a YAML inventory mapping hosts and ansible_user credentials, consumable by all downstream playbooks or roles requiring inventory input. + +## Dependencies & Relationships + +- Used by provision_pah.yml and lab onboarding modules for repeatable inventory creation. + +## Output/Result + +- Static inventory for PAH and lab automation, ready for immediate use or extension. diff --git a/olam/docs/templates/ingress_security_rules.j2.md b/olam/docs/templates/ingress_security_rules.j2.md new file mode 100644 index 0000000..7152e01 --- /dev/null +++ b/olam/docs/templates/ingress_security_rules.j2.md @@ -0,0 +1,28 @@ +# ingress_security_rules.j2 Documentation + +## Purpose & Overview + +Feature-conditional Jinja2 YAML template for generating ingress network/security rules in Oracle Linux Automation Manager labs. Always opens SSH, and conditionally includes rules for FreeIPA, PAH, cluster ports, and other core services based on feature flags. + +## When to Use + +Render this template to define security policies for cloud-played VMs in Oracle Linux Automation Manager workflows. Used at provisioning time or when modifying network policies/scenarios. + +## Key Variables & Inputs + +- Feature flags: use_freeipa, use_olam_pah, add_pah_ports, add_cluster_ports, add_haproxy_ports +- All rules are controlled by scenario toggles; SSH (22/TCP) is always opened + +## Task Breakdown + +- Emits list “instance_ingress_security_rules” for use in OCI/Ansible +- Includes only relevant rules for enabled services and demos, minimizing unnecessary attack surface + +## Dependencies & Relationships + +- Rendered/imported by create_instance.yml, cluster build flows, and network setup tasks +- Should always be paired with egress_security_rules.j2 for balanced security policy management + +## Output/Result + +- YAML block of ingress rules; imported into OCI security lists or lab firewalls diff --git a/olam/docs/templates/install_ipa.j2.md b/olam/docs/templates/install_ipa.j2.md new file mode 100644 index 0000000..464624e --- /dev/null +++ b/olam/docs/templates/install_ipa.j2.md @@ -0,0 +1,27 @@ +# install_ipa.j2 Documentation + +## Purpose & Overview + +Jinja2 template for a shell script that installs FreeIPA non-interactively. Passes domain/realm and admin passwords as Ansible variables for robust lab server deployment. + +## When to Use +Render and run as part of manual FreeIPA server installation within Oracle Linux Automation Manager labs, supporting hands-off clustering and identity workflow onboarding. + +## Key Variables & Inputs + +- ipaserver_realm, ipadm_password, ipaadmin_password +- Set in playbooks or roles using the template + +## Task Breakdown + +- Renders a shell script with all required flags for non-interactive ipa-server-install +- Handles all parameters (realm, passwords, input mode) for safe, reusable install + +## Dependencies & Relationships + +- Called by provision_free_ipa.yml (manual setup branch) +- Used for testing or in scenarios where the FreeIPA Ansible role is not used + +## Output/Result + +- Installs FreeIPA with provided configuration, creating a lab identity server diff --git a/olam/docs/templates/nginx.conf.j2.md b/olam/docs/templates/nginx.conf.j2.md new file mode 100644 index 0000000..29b6e20 --- /dev/null +++ b/olam/docs/templates/nginx.conf.j2.md @@ -0,0 +1,29 @@ +# nginx.conf.j2 Documentation + +## Purpose & Overview + +Feature-conditional Nginx configuration template for Oracle Linux Automation Manager labs. Renders a full Nginx config for web endpoints and HAProxy health checks, with modular toggles for HTTP and API endpoints. + +## When to Use + +Render the config when enabling Nginx for PAH or other web/app/health endpoints. Best for CI/CD, lab demos, or infrastructure onboarding scenarios needing HTTP(s) and service health endpoints. + +## Key Variables & Inputs + +- use_haproxy: Determines whether the 8080/health and /nginx-health server block is included. +- All other config is static or distributed default. + +## Task Breakdown + +- Base config is provided for Nginx logs, mime types, includes, and worker processes. +- If use_haproxy is true, exposes /nginx-health and /health endpoints for external requests on 8080. +- All configs are best practices derived from Oracle Linux Automation Manager lab experience. + +## Dependencies & Relationships + +- Used by provision_pah.yml and other playbooks that set up web endpoints. +- Should be paired with firewall and host provisioning for correct enablement. + +## Output/Result + +- Nginx configuration file ready for GUI/web service, health check, and API lab usage. diff --git a/olam/docs/templates/nginx.conf_v1.j2.md b/olam/docs/templates/nginx.conf_v1.j2.md new file mode 100644 index 0000000..1fd5415 --- /dev/null +++ b/olam/docs/templates/nginx.conf_v1.j2.md @@ -0,0 +1,27 @@ +# nginx.conf_v1.j2 Documentation + +## Purpose & Overview + +Template for a stock (but customizable) Nginx configuration for lab automation. Serves as a starting point for single- or multi-server Nginx setups in Oracle Linux Automation Manager, with easy extension for lab or demo scenarios. + +## When to Use + +When you need a baseline, modifiable Nginx setup in any Oracle Linux Automation Manager sample, hack, training, or onboarding lab scenario. + +## Key Variables & Inputs + +- No variables or dynamic template blocks; intended for static use or as a copy base. + +## Task Breakdown + +- Sets up default Nginx package config +- Details commented instructions for enabling HTTP/S blocks with best security practices +- Provides all includes, modules, log and MIME settings for Oracle Linux Automation Manager container/lab compatibility + +## Dependencies & Relationships + +- Usually called as part of playbook provisioning; used by provision_pah.yml, single-node install flows, or as a base config in config ops. + +## Output/Result + +- Confident starting point for rapid Nginx lab onboarding, secure serving for GUIs or API endpoints. diff --git a/olam/docs/templates/oci_vars.j2.md b/olam/docs/templates/oci_vars.j2.md new file mode 100644 index 0000000..76aa73e --- /dev/null +++ b/olam/docs/templates/oci_vars.j2.md @@ -0,0 +1,27 @@ +# oci_vars.j2 Documentation + +## Purpose & Overview + +Renders a YAML variables file with the current OCI compartment, VCN, subnet ID, and subnet DNS name, enabling repeatable and portable automation. + +## When to Use + +Include or render this file before automation that creates, moves, or destroys cloud resources in Oracle Cloud Infrastructure (OCI). + +## Key Variables & Inputs + +- my_compartment_id, my_vcn_id, my_subnet_id, my_subnet_domain_name — dynamically provided as facts or task vars. + +## Task Breakdown + +- No logic; direct mapping/substitution for dynamic config +- Makes all required OCI reference values available for downstream tasks, teardown, HA + +## Dependencies & Relationships + +- Generated by create_instance.yml and other workflow plays. +- Used by block.yml, build.yml, and network/teardown tasks. + +## Output/Result + +- YAML include_vars file with dynamic, consistent cloud IDs for automation. diff --git a/olam/docs/templates/playbook.yml.j2.md b/olam/docs/templates/playbook.yml.j2.md new file mode 100644 index 0000000..cea1346 --- /dev/null +++ b/olam/docs/templates/playbook.yml.j2.md @@ -0,0 +1,27 @@ +# playbook.yml.j2 Documentation + +## Purpose & Overview + +Template for a sample Ansible playbook to retrieve the OCI object storage namespace, validating Execution Environment setup and OCI module integration in Oracle Linux Automation Manager labs. + +## When to Use + +Use as a test or demo playbook to confirm OCI automation capabilities and correct connectivity within EEs or builder flows. + +## Key Variables & Inputs + +- No user input; runs on localhost. +- Calls oracle.oci.* module to access current tenancy namespace. + +## Task Breakdown + +- Runs a single task: fetches OCI object storage namespace and registers it in the output var. +- Prints the returned result as a debug message. + +## Dependencies & Relationships + +- Used by builder testing, CI workflows, or onboarding/EE validation. + +## Output/Result + +- Debug output containing the user's tenancy namespace—proof of successful OCI module operation and EE config. diff --git a/olam/docs/templates/receptor.conf.j2.md b/olam/docs/templates/receptor.conf.j2.md new file mode 100644 index 0000000..fcdd1f1 --- /dev/null +++ b/olam/docs/templates/receptor.conf.j2.md @@ -0,0 +1,29 @@ +# receptor.conf.j2 Documentation + +## Purpose & Overview + +Single-node receptor configuration for local/hybrid automation in Oracle Linux Automation Manager labs. Sets node ID, debug log level, TCP listener, control services, and selects local or ansible-runner worktype for command processing. + +## When to Use + +Use when running Oracle Linux Automation Manager/AWX labs or demos on individual lab nodes, for single-host or illustrative “mini-cluster” automation. + +## Key Variables & Inputs + +- control_node_ip (unique node ID) +- group_names controls worktype (local for control/hop, ansible-runner otherwise) + +## Task Breakdown + +- Configures basic receptor node settings +- Enables hybrid “local/ansible-runner” worktype switching for demo or test labs +- No complex logic; renders YAML for direct consumption + +## Dependencies & Relationships + +- Compared/paired with receptor_cluster.conf.j2 for full topology builds +- Used as a drop-in config for “test bench” labs or onboarding + +## Output/Result + +- Valid YAML receptor config for single-node/lab automation diff --git a/olam/docs/templates/receptor_cluster.conf.j2.md b/olam/docs/templates/receptor_cluster.conf.j2.md new file mode 100644 index 0000000..10ae5b1 --- /dev/null +++ b/olam/docs/templates/receptor_cluster.conf.j2.md @@ -0,0 +1,28 @@ +# receptor_cluster.conf.j2 Documentation + +## Purpose & Overview + +Jinja2 template for a YAML configuration file supporting mesh/clustered receptor setups in OLAM/AWX labs. Assigns unique node ID per host, sets TCP port, logs, and automation work command. + +## When to Use + +Generate when configuring distributed or HA automation cluster nodes that require peer-to-peer command and control (e.g., hybrid mesh clusters for lab demos). + +## Key Variables & Inputs + +- node ID is dynamically rendered from hostvars/inventory facts. +- Standard control services and work command as expected for local runner workflows. + +## Task Breakdown + +- Exposes all required fields for node mesh/agent setup. +- No logic or conditionals beyond node addressing. + +## Dependencies & Relationships + +- Used in provision_builder.yml or advanced mesh onboarding flows. +- Paired with single-node receptor.conf.j2 for comparison and lab role teaching. + +## Output/Result + +- Valid receptor mesh config for lab node, ready for mesh, cluster, or peer automation. diff --git a/olam/docs/templates/requirements.txt.j2.md b/olam/docs/templates/requirements.txt.j2.md new file mode 100644 index 0000000..1159159 --- /dev/null +++ b/olam/docs/templates/requirements.txt.j2.md @@ -0,0 +1,25 @@ +# requirements.txt.j2 Documentation + +## Purpose & Overview + +Template file listing Python packages for Oracle Linux Automation Manager EE/container builds. Ensures all pip dependencies are consistently provided when building/deploying automation runners or test environments. + +## When to Use + +Include as requirements.txt in ansible-builder or manual container image builds for Oracle Linux Automation Manager/AWX-based labs. + +## Key Variables & Inputs + +- Statically emits: requests (>=2.4.2), ovirt-engine-sdk-python (>=4.6.2), oci (>=2.155.0) + +## Task Breakdown + +- Used in container build context to install all required pip packages + +## Dependencies & Relationships + +- Paired with requirements.yml, bindep.txt, and execution_environment.yml.j2 for complete dependency management. + +## Output/Result + +- Ensures that EEs and containers have the correct Python libraries for OCI/oVirt/requests-based automation. diff --git a/olam/docs/templates/requirements.yml.j2.md b/olam/docs/templates/requirements.yml.j2.md new file mode 100644 index 0000000..6f2ea3e --- /dev/null +++ b/olam/docs/templates/requirements.yml.j2.md @@ -0,0 +1,26 @@ +# requirements.yml.j2 Documentation + +## Purpose & Overview + +Template for an Ansible requirements.yml for Galaxy collection dependencies—used by builder pipelines to ensure all Oracle OCI and oVirt modules are present in Execution Environments or CI/CD lab orchestration. + +## When to Use + +Include as requirements.yml in container and EI builds for automated dependency installation before executing test or onboarding tasks in Oracle Linux Automation Manager labs. + +## Key Variables & Inputs + +- Pinning of oracle.oci (>=5.5.0,<6.0.0) and inclusion of ovirt.ovirt + +## Task Breakdown + +- Outputs the Galaxy collection dependency list for inclusion by ansible-galaxy or ansible-builder + +## Dependencies & Relationships + +- Paired with requirements.txt, bindep.txt, and execution_environment.yml.j2 for a complete dependency lifecycle. +- Referenced by provision_builder.yml during container/EE build and lab orchestration flows. + +## Output/Result + +- All required modules and roles available for repeatable, reliable OLAM automation. diff --git a/olam/docs/terminate_instance.md b/olam/docs/terminate_instance.md new file mode 100644 index 0000000..2ceb2c2 --- /dev/null +++ b/olam/docs/terminate_instance.md @@ -0,0 +1,28 @@ +# terminate_instance.yml Documentation + +## Purpose & Overview + +Safely and fully destroys OCI resources associated with a lab deployment (instances, networking, state files), removing all remote artifacts and only performing local file cleanup after explicit user confirmation. + +## When to Use + +Use when needing to teardown a lab or demo environment, reclaim cloud resources, or ensure a clean state before next run or integration test. + +## Key Variables & Inputs + +- State is tracked in `.ansible-state`; only removes if present. +- Uses default_vars.yml for config/location and required credentials. + +## Task Breakdown + +- Loads state file, ensuring resources are tracked and exist. +- Deletes OCI instances, subnets, security lists, route tables, service gateways, internet gateways, and the VCN. +- Prompts the user interactively before any destructive local action (removal of state, hosts file, buffer dir, etc.). +- Robust error checking to avoid "phantom" deletions if state is unknown. + +## Dependencies & Relationships + +- Should always be called by (or as part of) create_instance.yml's teardown workflow or caller's clean-up logic. +- Needs the same OCI profile and config context as was used to create. + +## Output/Result diff --git a/olam/docs/update_all_rpms.md b/olam/docs/update_all_rpms.md new file mode 100644 index 0000000..0226024 --- /dev/null +++ b/olam/docs/update_all_rpms.md @@ -0,0 +1,28 @@ +# update_all_rpms.yml Documentation + +## Purpose & Overview + +Automates system-wide package updates for all Oracle Linux Automation Manager lab VMs or physical hosts, testing for required kernel reboots and performing them safely. + +## When to Use + +Run after any automated deployment, prior to integration testing, or as part of a regular maintenance schedule to apply OL security, feature, or bugfix updates. + +## Key Variables & Inputs + +- Applies to all:!localhost:!remote by default. +- `debug_enabled` can be set for output control. + +## Task Breakdown + +- Updates all O/S packages to latest with dnf, handling network/proxy as necessary. +- Ensures a safe, reliable upgrade with retries for open network scenarios. +- Detects if a reboot is required via needs-restarting and reboots only when necessary. +- Prints reboot requirement for admin attention on demand. + +## Dependencies & Relationships + +- Relies on host setup/credential priming first. +- Should be run as an include/import by create_instance.yml, lab reset scripts, or CI/CD pipelines. + +## Output/Result diff --git a/olvm/docs/README.md b/olvm/docs/README.md new file mode 100644 index 0000000..fadc270 --- /dev/null +++ b/olvm/docs/README.md @@ -0,0 +1,191 @@ +# Oracle Linux Virtualization Manager Automation Lab – Playbooks & Template Documentation + +## Overview + +This directory provides detailed documentation for every Ansible playbook and Jinja2 template found in `linux-virt-labs/olvm/`. + +- Each lab file is mapped 1:1 to a Markdown (`.md`) doc for rapid navigation, debugging, and advanced scenario-building. +- Use this index to onboard, extend, or troubleshoot end-to-end Oracle Linux Virtualization Manager cluster/lab automation. + +--- + +## Deploy Oracle Linux Virtualization Manager Using These Ansible Playbooks + +**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/olvm + ``` + +1. Install the required collections. + + ```shell + ansible-galaxy collection install -r requirements.yml + ``` + +1. Update the Oracle Linux Instance Configuration. + + ```shell + cat << EOF | tee instances.yml > /dev/null + compute_instances: + 1: + instance_name: "olvm" + type: "engine" + instance_ocpus: 2 + instance_memory: 32 + 2: + instance_name: "olkvm01" + type: "kvm" + instance_ocpus: 8 + instance_memory: 64 + 3: + instance_name: "olkvm02" + type: "kvm" + instance_ocpus: 8 + instance_memory: 64 + use_vnc_on_engine: true + EOF + ``` + +1. Create an Inventory file. + + ```shell + cat << EOF | tee hosts > /dev/null + localhost ansible_connection=local ansible_connection=local ansible_python_interpreter=/usr/bin/python3.6 + EOF + ``` + +1. Deploy the lab environment. + + ```shell + ansible-playbook create_instance.yml -i hosts -e "@instances.yml" + ``` + + **Note:** The free lab environment requires the extra variable `localhost_python_interpreter`, which sets `ansible_python_interpreter` for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules. Either remove, or update this variable to match your system's requirements. + + The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command. + + > **Important:** Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab. + +--- + +## Documentation Table + +### Playbooks – Index + +| Playbook | Summary | Related Templates/Files | +| --- | --- | --- | +| [build.yml](./build.md) | Provisions OCI compute instances, VNICs, VLAN, block storage. | create_block_storage.yml | +| [check_instance_available.yml](./check_instance_available.md) | Connectivity/fact check for all engine/KVM hosts. | | +| [configure_passwordless_ssh.yml](./configure_passwordless_ssh.md) | Sets up SSH trust between all engine/KVM hosts. | | +| [configure_secondary_nic.yml](./configure_secondary_nic.md) | Configures secondary NICs on engine/KVM hosts for cluster/storage. | etc_hosts_kvm.j2 | +| [create_block_storage.yml](./create_block_storage.md) | Attaches OCI block storage to VMs for storage domains. | | +| [create_hostfile_secondary_nic.yml](./create_hostfile_secondary_nic.md) | Writes secondary NIC hosts aliasing for KVM/engine. | etc_hosts_kvm.j2 | +| [create_instance.yml](./create_instance.md) | Top-level cluster orchestrator—bootstraps infra, nodes, overlay net, etc. | Most plays/templates | +| [create_vlan.yml](./create_vlan.md) | Provisions VLAN & NSG for advanced networking. | | +| [default_vars.yml](./default_vars.md) | Variables for all KVM, engine, storage, and cluster config. | | +| [ovirt_add_hosts.yml](./ovirt_add_hosts.md) | Adds KVM hosts to the Oracle Linux Virtualization Manager/oVirt engine/cluster. | | +| [ovirt_add_logical_network.yml](./ovirt_add_logical_network.md) | Adds logical network to Oracle Linux Virtualization Manager cluster for segmentation/testing. | | +| [ovirt_add_storage_domain.yml](./ovirt_add_storage_domain.md) | Adds storage domains for VMs and ISO images. | | +| [ovirt_check_hosts.yml](./ovirt_check_hosts.md) | Verifies KVM/oVirt hosts are online, ready, and registered. | | +| [ovirt_connection_test.yml](./ovirt_connection_test.md) | Tests connection/auth to Oracle Linux Virtualization Manager engine before further steps. | | +| [ovirt_create_vm_from_template.yml](./ovirt_create_vm_from_template.md) | Creates VMs from pre-imported templates. | | +| [ovirt_delete_host.yml](./ovirt_delete_host.md) | Removes KVM hosts from the cluster and decommissions. | | +| [ovirt_import_template.yml](./ovirt_import_template.md) | Imports VM/OVA templates to cluster storage domains. | | +| [ovirt_list_hosts.yml](./ovirt_list_hosts.md) | Lists all available KVM/oVirt hosts in the cluster. | | +| [provision_instance_basics.yml](./provision_instance_basics.md) | Core user/SSH/locale prep for all hosts. | | +| [provision_olvm_engine_publickey.yml](./provision_olvm_engine_publickey.md) | Copies engine pubkey to KVM hosts for trust. | | +| [provision_olvm_engine.yml](./provision_olvm_engine.md) | Configures Oracle Linux Virtualization Manager engine & exposes host/cluster for control plane. | answer_file.j2 | +| [provision_vnc.yml](./provision_vnc.md) | Adds VNC/GUI capability to engine nodes in the lab. | | +| [requirements.yml](./requirements.md) | Ansible Galaxy collection dependencies for cluster automation. | | +| [terminate_instance.yml](./terminate_instance.md) | Fully tears down OCI and resets all resource state. | | + +--- + +### Templates – Index + +| Template | Description & Usage | +| --- | --- | +| [answer_file.j2](./templates/answer_file.j2.md) | Automated installer answers for unattended setups. | +| [egress_security_rules.j2](./templates/egress_security_rules.j2.md) | YAML variable: allows all TCP traffic from VMs. | +| [etc_hosts_kvm.j2](./templates/etc_hosts_kvm.j2.md) | Generates /etc/hosts entries for secondary-NIC HA labs. | +| [ingress_security_rules.j2](./templates/ingress_security_rules.j2.md) | YAML variable: allows feature-based ports per scenario. | +| [oci_vars.j2](./templates/oci_vars.j2.md) | Core OCI resource mapping file for automated flows. | + +--- + +### Tree Listing + +```markdown +└── olvm + ├── build.md + ├── check_instance_available.md + ├── configure_passwordless_ssh.md + ├── configure_secondary_nic.md + ├── create_block_storage.md + ├── create_hostfile_secondary_nic.md + ├── create_vlan.md + ├── default_vars.md + ├── ovirt_add_hosts.md + ├── ovirt_add_logical_network.md + ├── ovirt_add_storage_domain.md + ├── ovirt_check_hosts.md + ├── ovirt_connection_test.md + ├── ovirt_create_vm_from_template.md + ├── ovirt_delete_host.md + ├── ovirt_import_template.md + ├── ovirt_list_hosts.md + ├── provision_instance_basics.md + ├── provision_olvm_engine_publickey.md + ├── provision_olvm_engine.md + ├── provision_vnc.md + ├── README.md + ├── requirements.md + ├── terminate_instance.md + └── templates +    ├── answer_file.j2.md +    ├── egress_security_rules.j2.md +    ├── etc_hosts_kvm.j2.md +    ├── ingress_security_rules.j2.md +    └── oci_vars.j2.md +``` + +--- + +## Relationships and Workflow + +- **create_instance.yml** is the primary orchestrator—handles resource setup, network config, host prepping, cluster linking, VNC enable, storage-provisioning, and tear-down. +- **build.yml** provisions core nodes and ensures VMs are cluster-ready. +- **ovirt_add_hosts.yml**, **ovirt_add_logical_network.yml**, **ovirt_add_storage_domain.yml**: incremental cluster topology enablement, networking, and storage. +- **Templates** are always rendered by parent playbooks to automate config, security, or hosts file population. +- Onboarding, troubleshooting, and advanced test scenarios are enabled by per-file documentation and this README. + +--- + +## Tips and Best Practices + +- Review each individual Markdown doc for file-specific details, usage notes, and in-context examples. +- Always use version-pinned dependency management via `requirements.yml`. +- Keep code and docs in sync: update the corresponding `.md` file for any playbook, role, or template change. + +--- + +## References + +- [Oracle Cloud Infrastructure Documentation](https://docs.oracle.com/en-us/iaas/Content/home.htm) +- [OCI Ansible Collection](https://docs.oracle.com/en-us/iaas/tools/oci-ansible-collection/) +- [Oracle Linux Virtualization Manager](https://docs.oracle.com/en/virtualization/oracle-linux-virtualization-manager/) + +--- + +For troubleshooting, edge use cases, or advanced onboarding, see individual `.md` files in this directory. diff --git a/olvm/docs/build.md b/olvm/docs/build.md new file mode 100644 index 0000000..30e474d --- /dev/null +++ b/olvm/docs/build.md @@ -0,0 +1,31 @@ +# build.yml Documentation + +## Purpose & Overview + +Automates provisioning of OCI compute instances for Oracle Linux Virtualization Manager labs, supports custom instance types and sizing, configures public/private/VLAN networking, attaches storage, and prepares all instance facts for downstream automation. + +## When to Use + +Use as a core step in lab provisioning workflows—run by an orchestrator, e.g., create_instance.yml. + +## Key Variables & Inputs + +- `my_availability_domain`, `my_compartment_id`, `ol_image_id`, `instance_shape`, `block_devices` +- instance definition via items: type, instance_name, instance_ocpus, instance_memory, etc. +- Networking: my_subnet1_id, my_subnet2_id, my_vlan_id + +## Task Breakdown + +- Launches a compute instance using Oracle Cloud modules, sets core facts and updates inventory. +- Attaches primary and secondary (private, VLAN) networks as appropriate for each role (engine, kvm). +- Attaches block storage for VM domains via included tasks. +- Handles retries, idempotency, and logging throughout. +- Updates both runtime and file-based inventories for ongoing config. + +## Dependencies & Relationships + +- Included by higher-level orchestrators (create_instance.yml, etc.). +- Delegates to create_block_storage.yml for storage attachment. +- Synchronizes state via local .ansible-state file. + +## Output/Result diff --git a/olvm/docs/check_instance_available.md b/olvm/docs/check_instance_available.md new file mode 100644 index 0000000..5962612 --- /dev/null +++ b/olvm/docs/check_instance_available.md @@ -0,0 +1,28 @@ +# check_instance_available.yml Documentation + +## Purpose & Overview + +Ensures newly created engine and KVM instances are accessible via SSH, gathers minimal facts, and optionally prints inventory and variable info for debugging. + +## When to Use + +Run after provisioning to validate that all virtualized infrastructure is online, networked, and ready for downstream automated configuration. + +## Key Variables & Inputs + +- Hosts: engine, kvm (excluding localhost) +- Variables from default_vars.yml and oci_vars.yml +- debug_enabled (verbosity toggle) + +## Task Breakdown + +- Waits for SSH/Ansible connection for each host via port 22. +- Gathers all available facts for each instance for inventory and audit. +- Optionally prints group and hostvars for troubleshooting/config validation. + +## Dependencies & Relationships + +- Should be triggered after build.yml or instance bring-up workflow. +- Prerequisite for further task orchestration requiring fact collection. + +## Output/Result diff --git a/olvm/docs/configure_passwordless_ssh.md b/olvm/docs/configure_passwordless_ssh.md new file mode 100644 index 0000000..628ecb4 --- /dev/null +++ b/olvm/docs/configure_passwordless_ssh.md @@ -0,0 +1,30 @@ +# configure_passwordless_ssh.yml Documentation + +## Purpose & Overview + +Enables password-less SSH for all engine and KVM hosts, streamlining secure automation by exchanging public keys and ensuring mutually trusted authorized_keys/known_hosts configuration. + +## When to Use + +Use after host or VM provisioning to prepare the cluster for agentless orchestration, configuration management, or delegation of control from Ansible Tower/AWX/Oracle Linux Automation Manager. + +## Key Variables & Inputs + +- Hosts: engine, kvm (excluding localhost) +- `username`: User account on target systems. +- `private_key`: Basename for SSH private/public key files. +- Uses all hosts in inventory minus localhost for key distribution. + +## Task Breakdown + +- For each host: generates an SSH keypair for `username` user (if missing). +- Fetches public keys from all hosts and distributes them via authorized_keys. +- SSH known_hosts is populated for peer recognition and trust. +- Optionally prints hostvars and network info when debugging is enabled. + +## Dependencies & Relationships + +- Requires SSH reachability between all hosts. +- Referenced by main orchestrator and initial lab bring-up playbooks. + +## Output/Result diff --git a/olvm/docs/configure_secondary_nic.md b/olvm/docs/configure_secondary_nic.md new file mode 100644 index 0000000..3f2a590 --- /dev/null +++ b/olvm/docs/configure_secondary_nic.md @@ -0,0 +1,29 @@ +# configure_secondary_nic.yml Documentation + +## Purpose & Overview + +Configures a secondary network interface on engine and kvm nodes in Oracle Linux Virtualization Manager automation labs. Ensures static IP, DNS, and cluster communication readiness across lab nodes. + +## When to Use + +Run after instance provisioning when a secondary NIC is required for out-of-band management, storage traffic, or advanced networking scenarios. + +## Key Variables & Inputs + +- Hosts: engine, kvm +- Gathers all core instance, Virtual Network Interface Card (VNIC), and subnet information via facts modules and OCI API. + +## Task Breakdown + +- Finds instance/vnic IDs and details for the second NIC (via OCI modules and json_query). +- Retrieves the secondary VNIC’s private IP and MAC address. +- Sets up the correct local system network interface, assigning static IP/DNS. +- Checks if the host is already part of an Oracle Linux Virtualization Manager cluster before making changes (for idempotency). +- Adds DNS and network IP config atomically and securely. + +## Dependencies & Relationships + +- Requires prior setup of default_vars.yml and oci_vars.yml. +- Invoked by create_instance.yml or cluster-setup orchestrators. + +## Output/Result diff --git a/olvm/docs/create_block_storage.md b/olvm/docs/create_block_storage.md new file mode 100644 index 0000000..6846bce --- /dev/null +++ b/olvm/docs/create_block_storage.md @@ -0,0 +1,27 @@ +# create_block_storage.yml Documentation + +## Purpose & Overview + +Automates creation, configuration, and attachment of block storage domains for lab VMs in Oracle Linux Virtualization Manager, enabling persistent and scalable storage for KVM-based infrastructure. + +## When to Use + +Execute when creating or extending storage domains for KVM/engine nodes in lab, development, or testing environments where Oracle Linux VMs require extra disks. + +## Key Variables & Inputs + +- Target storage_name, host, block size, compartment/ad, and instance_id inherited from upstream playbooks. +- Must be part of instance creation or post-provision VM expansion. + +## Task Breakdown + +- Creates OCI blockstorage volumes named by storage_name. +- Attaches block to target instance with full error/retry handling. +- Records and outputs resulting IDs and resource information as facts for follow-up configuration or mounting. + +## Dependencies & Relationships + +- Called by build.yml with correct item and host context. +- Requires valid OCI config/profile/variables and instance provisioning prior to execution. + +## Output/Result diff --git a/olvm/docs/create_hostfile_secondary_nic.md b/olvm/docs/create_hostfile_secondary_nic.md new file mode 100644 index 0000000..f063454 --- /dev/null +++ b/olvm/docs/create_hostfile_secondary_nic.md @@ -0,0 +1,26 @@ +# create_hostfile_secondary_nic.yml Documentation + +## Purpose & Overview + +Generates and manages a host file mapping secondary NICs for KVM and engine nodes in the Oracle Linux Virtualization Manager lab, ensuring correct network and connectivity setup in clustered environments. + +## When to Use + +Run after instances and secondary network interfaces are provisioned, to create a hosts file with static mappings and support cluster-wide communication or storage/management segmentation. + +## Key Variables & Inputs + +- Requires up-to-date inventory, host facts, and network provisioning. +- Uses Ansible facts to resolve hostnames and secondary NIC details. + +## Task Breakdown + +- Gathers/subscribes necessary facts from engine and KVM hosts. +- Writes/updates a host file (likely /etc/hosts or a designated path) to match secondary NICs to host aliases or required IP addressing. + +## Dependencies & Relationships + +- Usually run as a step in network finalization, right after secondary NIC and static IP assignment playbooks. +- Must be in sync with running instance state and up-to-date facts. + +## Output/Result diff --git a/olvm/docs/create_instance.md b/olvm/docs/create_instance.md new file mode 100644 index 0000000..329a930 --- /dev/null +++ b/olvm/docs/create_instance.md @@ -0,0 +1,30 @@ +# create_instance.yml Documentation + +## Purpose & Overview + +Orchestrates end-to-end cloud and networking provisioning for an Oracle Linux Virtualization Manager test/lab cluster. Launches engine/kvm VMs, configures primary/subnet/VLAN networking and storage, syncs facts/state, and manages host inventories. + +## When to Use + +Run to fully build, scale, or reset a multi-VM Oracle Linux Virtualization Manager cluster/lab in OCI, with robust network and storage integration. + +## Key Variables & Inputs + +- All credential, AD, VCN/network, and image vars (default_vars.yml) +- engine/kvm role, SSH credentials, block count, subnet/VLAN config + +## Task Breakdown + +- Gathers/sets facts on OCI/region/compartment, prepares .ansible-state ID tracking +- Provisions VCN, routing, subnets, security lists, images, and computes +- Loops over each instance—configuring public/private NICs, storage, VLANs, and facts +- Updates both in-memory and ini-style host inventories for cluster readiness + +## Dependencies & Relationships + +- Calls build.yml, create_block_storage.yml, and imports cluster/host prep tasks +- Used as main host/nodeset orchestration by bootstrapping scripts and teardown tasks + +## Output/Result + +- Full OLVM lab with engine and kvm hosts, all required secondary networks/storage, and idempotent state tracking for dev/test/CI/CD. diff --git a/olvm/docs/create_vlan.md b/olvm/docs/create_vlan.md new file mode 100644 index 0000000..261d289 --- /dev/null +++ b/olvm/docs/create_vlan.md @@ -0,0 +1,28 @@ +# create_vlan.yml Documentation + +## Purpose & Overview + +Automates the creation of an OCI VLAN (layer 2 network) and associated security group for KVM and engine hosts in Oracle Linux Virtualization Manager labs—enables advanced networking topologies, isolation, and segmentation. + +## When to Use + +Run after VCN and subnets are provisioned, before attaching secondary VLANs or overlaying virtualized environments on lab VMs or clouds. + +## Key Variables & Inputs + +- Networking resource IDs (compartment, VCN, route table), VLAN CIDR blocks, plus OCI config/profile context. +- Security rules are set per default lab communication needs. + +## Task Breakdown + +- Creates an OCI NSG (network security group) for the VLAN, writes its OCID to a state file for orchestration tracking. +- Adds egress (all) and restricted ingress (10.0.0.0/16) rules to the VLAN NSG. +- Provisions a VLAN object including NSG, assigns correct tag, attaches to public route table, and writes resource OCID to state file. + +## Dependencies & Relationships + +- Requires VCNs, base subnets, and routing already be provisioned (by create_instance.yml or equivalent). +- Upstream dependencies: block.yml, build.yml, etc. +- Written OCIDs are used by future playbooks for topology expansion and deletion. + +## Output/Result diff --git a/olvm/docs/default_vars.md b/olvm/docs/default_vars.md new file mode 100644 index 0000000..1df6992 --- /dev/null +++ b/olvm/docs/default_vars.md @@ -0,0 +1,28 @@ +# default_vars.yml Documentation + +## Purpose & Overview + +Holds all global variables and toggles for Oracle Linux Virtualization Manager lab deployments, covering instance configuration, network setup, storage, KVM/engine role toggles, cloud resource values, and provisioning flags. + +## When to Use + +Always include as a vars_files in orchestrator and provisioning playbooks for consistent, reproducible deployments. + +## Key Variables & Inputs + +- Core instance variables (compute_instances, shape, ocpus, memory, images) +- Storage, SSH, user, and password fields +- Networking (subnets, VCN, VLAN) +- Tuning for HA, DevOps, clustering, firewalls, proxy, and feature toggles + +## Task Breakdown + +- Exports all required config and parameters for use by downstream tasks and modules. +- Enables safe, transparent customization and immediate repeatability (lab, demo, or test scenarios). + +## Dependencies & Relationships + +- Included by every major playbook, referenced by most templates. +- User can override at runtime or by file edit for scenario-specific configuration. + +## Output/Result diff --git a/olvm/docs/ovirt_add_hosts.md b/olvm/docs/ovirt_add_hosts.md new file mode 100644 index 0000000..fcddb07 --- /dev/null +++ b/olvm/docs/ovirt_add_hosts.md @@ -0,0 +1,27 @@ +# ovirt_add_hosts.yml Documentation + +## Purpose & Overview + +Automates the process of adding KVM hosts (hypervisors/compute nodes) to an oVirt/Oracle Linux Virtualization Manager cluster, forming the scalable base for VM workloads and distributed management. + +## When to Use + +Run as part of an Oracle Linux Virtualization Manager environment bootstrap, or when a new KVM host needs to be integrated into an existing cluster for scale-out, HA, or migration scenarios. + +## Key Variables & Inputs + +- Target cluster information, host credentials, and inventory determined upstream. +- Requires KVM hosts to be available and SSH-reachable. + +## Task Breakdown + +- Registers/validates each KVM host with the oVirt/Oracle Linux Virtualization Manager engine. +- Tests connectivity, gathers host state, and ensures the hypervisor is attached to the target cluster. +- Handles errors and reports any failed adds for troubleshooting. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and cluster setup sequences. +- Ties in with all networking, VLAN, and security configuration plays/templates. + +## Output/Result diff --git a/olvm/docs/ovirt_add_logical_network.md b/olvm/docs/ovirt_add_logical_network.md new file mode 100644 index 0000000..28d603c --- /dev/null +++ b/olvm/docs/ovirt_add_logical_network.md @@ -0,0 +1,26 @@ +# ovirt_add_logical_network.yml Documentation + +## Purpose & Overview + +Automates adding a logical network to an oVirt/Oracle Linux Virtualization Manager cluster, enabling segmented traffic, improved security, and sophisticated lab/demo topologies. + +## When to Use + +Run when you need additional logical networks (beyond default) to support workload separation, HA, custom routing, or special-purpose VMs. + +## Key Variables & Inputs + +- Network definition, VLAN/segment IDs, cluster/host info, all determined by lab scenario and upstream inventory. + +## Task Breakdown + +- Uses Ansible oVirt modules to add and configure the desired logical network in the Oracle Linux Virtualization Manager cluster. +- Ensures new networks are applied to the right clusters and attached to the correct hosts. +- Handles VLAN tags, MTU, and custom lab segmentation options. + +## Dependencies & Relationships + +- Called after hosts and the Oracle Linux Virtualization Manager engine/cluster are online. +- Must synchronize with physical/VM NIC configuration for lab scenarios. + +## Output/Result diff --git a/olvm/docs/ovirt_add_storage_domain.md b/olvm/docs/ovirt_add_storage_domain.md new file mode 100644 index 0000000..565e637 --- /dev/null +++ b/olvm/docs/ovirt_add_storage_domain.md @@ -0,0 +1,27 @@ +# ovirt_add_storage_domain.yml Documentation + +## Purpose & Overview + +Automates adding new storage domains to the oVirt/Oracle Linux Virtualization Manager cluster—enabling shared storage for VM provisioning, HA, and advanced disk management scenarios. + +## When to Use + +Run when expanding the storage pool, onboarding new applications, or setting up D/R, backup, or fast scaling capabilities in the virtual lab. + +## Key Variables & Inputs + +- Storage domain configuration (type, backend, connection info) +- Cluster/engine credentials and working infrastructure state + +## Task Breakdown + +- Uses Ansible's oVirt modules to define and add storage domains. +- Handles config, host assignment, and reporting details. +- Validates success and outputs errors/warnings for failed storage registration. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and cluster orchestration. +- Dependencies on Oracle Linux Virtualization Manager/engine, physical or cloud-based storage, and previous block provisioning. + +## Output/Result diff --git a/olvm/docs/ovirt_check_hosts.md b/olvm/docs/ovirt_check_hosts.md new file mode 100644 index 0000000..483e6a8 --- /dev/null +++ b/olvm/docs/ovirt_check_hosts.md @@ -0,0 +1,25 @@ +# ovirt_check_hosts.yml Documentation + +## Purpose & Overview + +Verifies KVM/oVirt hosts are reachable, healthy, and capable of participating in Oracle Linux Virtualization Manager clusters. Checks connectivity, authentication, status, and configuration readiness. + +## When to Use + +Run after provisioning/adding new hosts to validate cluster integrity before VM deployment, storage attach, or role expansion. + +## Key Variables & Inputs + +- Host credentials, cluster details, inventory provided by orchestrator playbook/group. + +## Task Breakdown + +- Uses Ansible's oVirt modules to check host reachability and configuration. +- Produces debug output for immediate operational troubleshooting. + +## Dependencies & Relationships + +- Recommended to run after ovirt_add_hosts.yml and before VM creation. +- Integrated with larger Oracle Linux Virtualization Manager install/test flows. + +## Output/Result diff --git a/olvm/docs/ovirt_connection_test.md b/olvm/docs/ovirt_connection_test.md new file mode 100644 index 0000000..e4d4e07 --- /dev/null +++ b/olvm/docs/ovirt_connection_test.md @@ -0,0 +1,25 @@ +# ovirt_connection_test.yml Documentation + +## Purpose & Overview + +Tests connection to the oVirt/Oracle Linux Virtualization Manager engine, ensuring API/service reachability and basic authentication before continuing cluster configuration or maintenance. + +## When to Use + +Run just after engine and host provisioning, before triggers like host/network/add/import or D/R orchestration. + +## Key Variables & Inputs + +- Engine address and credentials (host/group vars, default_vars.yml) + +## Task Breakdown + +- Establishes a connection to the oVirt/Oracle Linux Virtualization Manager API endpoint. +- Validates credentials, outputs status or error. + +## Dependencies & Relationships + +- Precedes any cluster management tasks that require engine communication. +- Reports issues before downstream failures occur. + +## Output/Result diff --git a/olvm/docs/ovirt_create_vm_from_template.md b/olvm/docs/ovirt_create_vm_from_template.md new file mode 100644 index 0000000..cdfdba8 --- /dev/null +++ b/olvm/docs/ovirt_create_vm_from_template.md @@ -0,0 +1,27 @@ +# ovirt_create_vm_from_template.yml Documentation + +## Purpose & Overview + +Automates creation of new VMs from existing OVA or template images in Oracle Linux Virtualization Manager, enabling rapid scaling of lab, test, or DR workloads with repeatable configuration. + +## When to Use + +Run when needing to deploy new VMs based on golden images/templates for standardized lab, student, or integration environments. + +## Key Variables & Inputs + +- Template name, cluster/host, and VM inventory determined by upstream playbook context. +- Storage/CD-ROM and network settings inherited from environment and prior steps. + +## Task Breakdown + +- Uses Ansible's oVirt modules to create/import VMs from OVA/template. +- Customizes VM definition (CPU, storage, network) to match lab requirements. +- Reports status and any errors to orchestrator/CI logs for troubleshooting. + +## Dependencies & Relationships + +- Recipe is dependent on existing imported OVA/template (from ovirt_import_template.yml). +- Tightly coupled to cluster and storage domain state. + +## Output/Result diff --git a/olvm/docs/ovirt_delete_host.md b/olvm/docs/ovirt_delete_host.md new file mode 100644 index 0000000..0716987 --- /dev/null +++ b/olvm/docs/ovirt_delete_host.md @@ -0,0 +1,26 @@ +# ovirt_delete_host.yml Documentation + +## Purpose & Overview + +Automates removal of a KVM/oVirt/Oracle Linux Virtualization Manager host from the cluster. Ensures accurate, safe clean-up for decommissioning, migration, or failure scenarios. + +## When to Use + +Run to remove stale, failed, or decommissioned hosts from an Oracle Linux Virtualization Manager cluster, ensuring environment health and management confidence. + +## Key Variables & Inputs + +- Host credentials and inventory (target host must be identified) +- Any cluster-specific locks or HA states must be handled + +## Task Breakdown + +- Uses Ansible oVirt modules to delete a host from the engine. +- Optionally waits or runs post-removal checks to confirm success. + +## Dependencies & Relationships + +- Relies on previous host and cluster setup (host must exist in engine before deletion). +- May be triggered by teardown routines or as a manual admin action. + +## Output/Result diff --git a/olvm/docs/ovirt_import_template.md b/olvm/docs/ovirt_import_template.md new file mode 100644 index 0000000..d1cefe5 --- /dev/null +++ b/olvm/docs/ovirt_import_template.md @@ -0,0 +1,26 @@ +# ovirt_import_template.yml Documentation + +## Purpose & Overview + +Automates importing external OVA or template images into an oVirt/Oracle Linux Virtualization Manager lab environment, providing a consistent “golden image” base for VM deployment, student labs, or proof-of-concept setups. + +## When to Use + +Run when bringing in new templates, updating base images, migrating between clouds/platforms, or resetting cluster training instances. + +## Key Variables & Inputs + +- Template/OVA URL, cluster/host/engine information +- Storage domain and connection details from surrounding environment + +## Task Breakdown + +- Uses Ansible and oVirt modules to import or register an OVA/template to the local storage domain. +- Validates and reports on import status, outputting result details for lab audit or troubleshooting. + +## Dependencies & Relationships + +- Precedes (and is required by) ovirt_create_vm_from_template.yml for VM instantiation. +- Consumed by create_instance.yml as part of full cluster workflows. + +## Output/Result diff --git a/olvm/docs/ovirt_list_hosts.md b/olvm/docs/ovirt_list_hosts.md new file mode 100644 index 0000000..c18dd54 --- /dev/null +++ b/olvm/docs/ovirt_list_hosts.md @@ -0,0 +1,25 @@ +# ovirt_list_hosts.yml Documentation + +## Purpose & Overview + +Lists all KVM/oVirt hosts currently registered in the Oracle Linux Virtualization Manager cluster. Used for inventory validation, troubleshooting host state, and reporting available compute resources to operators/admins. + +## When to Use + +Run after host provisioning, removal, or cluster modifications to audit current lab infrastructure. + +## Key Variables & Inputs + +- Engine and cluster credentials, host group inventory from upstream playbooks. + +## Task Breakdown + +- Uses Ansible's oVirt modules to enumerate all active/registered compute/hypervisor hosts. +- Outputs full host details and status for review, audit, or integration with other tools. + +## Dependencies & Relationships + +- Always up-to-date with the actual Oracle Linux Virtualization Manager cluster state. +- Typically run after ovirt_add_hosts.yml, ovirt_delete_host.yml, or as a health check step. + +## Output/Result diff --git a/olvm/docs/provision_instance_basics.md b/olvm/docs/provision_instance_basics.md new file mode 100644 index 0000000..1279f0a --- /dev/null +++ b/olvm/docs/provision_instance_basics.md @@ -0,0 +1,29 @@ +# provision_instance_basics.yml Documentation + +## Purpose & Overview + +Handles foundational configuration for a newly provisioned VM or host in Oracle Linux Virtualization Manager labs: expands root FS, sets up user accounts, ensures password-less sudo and SSH, and configures locale and temporary directories. + +## When to Use + +Run as one of the first steps after bringing KVM/engine nodes online, ensuring their environments are lab-ready for automation. + +## Key Variables & Inputs + +- username, user_default_password, private_key, debug_enabled, etc. +- Inherits host groups and variables from higher-level provisioning plays. + +## Task Breakdown + +- Expands root partition (oci-growfs). +- Creates/configures user with sudo and authorized key. +- Sets password-less sudo access. +- Creates Ansible temp directory as user. +- Adds locale settings and enables denied packet logging in firewall if needed. + +## Dependencies & Relationships + +- Consumed by create_instance.yml and checked by subsequent automation. +- Reads from default_vars.yml and oci_vars.yml. + +## Output/Result diff --git a/olvm/docs/provision_olvm_engine.md b/olvm/docs/provision_olvm_engine.md new file mode 100644 index 0000000..7c7f4b4 --- /dev/null +++ b/olvm/docs/provision_olvm_engine.md @@ -0,0 +1,27 @@ +# provision_olvm_engine.yml Documentation + +## Purpose & Overview + +Deploys and configures the Oracle Linux Virtualization Manager (oVirt) Engine on a dedicated VM/host, prepping the management and control plane for KVM virtualization clusters. + +## When to Use + +Run to bring up a new Oracle Linux Virtualization Manager control/engine, when rebuilding the engine, or onboarding new management topology in the lab/test infrastructure. + +## Key Variables & Inputs + +- Host: engine group +- Requires all engine and base variables set (default_vars.yml, cluster info, engine image/version) + +## Task Breakdown + +- Installs the engine RPMs/OVA/templates as required. +- Handles engine user setup, initial configuration, connectivity validation, and base service enablement/startup. +- Exposes configuration (address, host, port) for subsequent playbooks and inventory. + +## Dependencies & Relationships + +- Consumed by orchestrators and subsequent cluster deployments. +- Related doc: provision_olvm_engine_publickey.yml for trust setup. + +## Output/Result diff --git a/olvm/docs/provision_olvm_engine_publickey.md b/olvm/docs/provision_olvm_engine_publickey.md new file mode 100644 index 0000000..0b9a84b --- /dev/null +++ b/olvm/docs/provision_olvm_engine_publickey.md @@ -0,0 +1,26 @@ +# provision_olvm_engine_publickey.yml Documentation + +## Purpose & Overview + +Copies the Oracle Linux Virtualization Manager engine's SSH public key to all KVM nodes in the cluster, facilitating secure agentless setup, host registration, and trust for further automated roles/workflows. + +## When to Use + +Run after initial engine and host provisioning, and before adding KVM nodes to the cluster or running automation requiring password-less control/registration. + +## Key Variables & Inputs + +- Public/private key names and locations +- Target KVM hosts in inventory + +## Task Breakdown + +- Copies or distributes the engine's id_rsa.pub authorized_keys entry to all KVM hosts, updating or configuring as needed for role assignment. +- Optionally validates correct key propagation for security. + +## Dependencies & Relationships + +- Must run after host/user initialization. +- Often required by ovirt_add_hosts.yml and automated trust establishment steps in Oracle Linux Virtualization Manager/AWX/CI setups. + +## Output/Result diff --git a/olvm/docs/provision_vnc.md b/olvm/docs/provision_vnc.md new file mode 100644 index 0000000..b49c174 --- /dev/null +++ b/olvm/docs/provision_vnc.md @@ -0,0 +1,28 @@ +# provision_vnc.yml Documentation + +## Purpose & Overview + +Installs and configures GNOME and TigerVNC server for engine nodes in Oracle Linux Virtualization Manager, providing graphical access for admin, troubleshooting, or desktop/desktop-automation use. + +## When to Use + +Run after engine host provisioning, when GUI login or remote desktop access is required for setup, demos, or advanced debugging in virtual lab infrastructure. + +## Key Variables & Inputs + +- Hosts: engine +- Username, password, geometry, and VNC port definition. + +## Task Breakdown + +- Installs all packages required for graphical sessions and VNC (Server with GUI, tigervnc, etc.) +- Sets the system to default to graphical.target. +- Creates the user’s .vnc directory and a secure password file. +- Configures session (geometry, GNOME) and enables a systemd VNC service for runtime access. + +## Dependencies & Relationships + +- Called after classic host configuration +- May be referenced by GUI automation, test, or remote onboarding processes + +## Output/Result diff --git a/olvm/docs/requirements.md b/olvm/docs/requirements.md new file mode 100644 index 0000000..2c2d873 --- /dev/null +++ b/olvm/docs/requirements.md @@ -0,0 +1,26 @@ +# requirements.yml Documentation + +## Purpose & Overview + +Defines the Ansible Galaxy collections needed to run all automation in the Oracle Linux Virtualization Manager lab directory—ensures all network, VM, storage, and platform tasks have tested, compatible dependencies. + +## When to Use + +Install these collections before any major playbook or role run: + +```bash +ansible-galaxy collection install -r requirements.yml +``` + +For reproducibility and to avoid module-not-found errors. + +## Collections Listed + +- ansible.posix, community.general, freeipa.ansible_freeipa, community.crypto, oracle.oci, ovirt.ovirt, containers.podman, and others depending on feature set. + +## Dependencies & Relationships + +- Every playbook and role in the cluster runs against these tested module versions. +- YAML role/collection versions can be updated for new features or environments as needed. + +## Output/Result diff --git a/olvm/docs/templates/answer_file.j2.md b/olvm/docs/templates/answer_file.j2.md new file mode 100644 index 0000000..c04663e --- /dev/null +++ b/olvm/docs/templates/answer_file.j2.md @@ -0,0 +1,24 @@ +# answer_file.j2 Documentation + +## Purpose & Overview + +Jinja2 template for an answer file to seed automated (unattended) setups or installs for oVirt/Oracle Linux Virtualization Manager, supporting streamlined, repeatable deployments. + +## When to Use + +Generate as a config file for answering installer prompts for the Oracle Linux Virtualization Manager engine, hosts, or infrastructure workflows; especially useful for CI or repeated lab setups. + +## Key Variables & Inputs + +- Driven by parent playbooks, roles, and environment variables. + +## Task Breakdown + +- Provides a text file with variable content and responses, supporting automation and minimizing manual input during server/provisioner runs. + +## Dependencies & Relationships + +- Rendered by engine or orchestrator setup playbooks. +- Consumed by Oracle Linux Virtualization Manager/engine/host install scripts or CLI tools. + +## Output/Result diff --git a/olvm/docs/templates/egress_security_rules.j2.md b/olvm/docs/templates/egress_security_rules.j2.md new file mode 100644 index 0000000..9de058e --- /dev/null +++ b/olvm/docs/templates/egress_security_rules.j2.md @@ -0,0 +1,25 @@ +# egress_security_rules.j2 Documentation + +## Purpose & Overview + +Jinja2/YAML template that defines default egress security rules for OCI VMs—allows unrestricted egress (all TCP traffic) for networking flexibility in Oracle Linux Virtualization Manager labs. + +## When to Use + +Include in Ansible security list configuration tasks to grant outgoing network access to all hosts by default (matches lab/testbed scenarios). + +## Key Variables & Inputs + +- Static structure; no variable substitutions. + +## Task Breakdown + +- Exposes the variable `instance_egress_security_rules`, listing: + - Destination: "0.0.0.0/0" (all traffic) + - Protocol: 6 (TCP) + +## Dependencies & Relationships + +- Referenced by create_instance.yml or any network/security automation playbook for VCN/lab setup. + +## Output/Result diff --git a/olvm/docs/templates/etc_hosts_kvm.j2.md b/olvm/docs/templates/etc_hosts_kvm.j2.md new file mode 100644 index 0000000..9026eaf --- /dev/null +++ b/olvm/docs/templates/etc_hosts_kvm.j2.md @@ -0,0 +1,24 @@ +# etc_hosts_kvm.j2 Documentation + +## Purpose & Overview + +Jinja2 template for rendering the /etc/hosts file on KVM nodes, mapping all relevant hostnames/IPs for intra-cluster communication and service reliability. + +## When to Use + +Use during provisioning or reconfiguration of network connectivity for KVM nodes, ensuring all cluster members can resolve each other by short and fully-qualified name. + +## Key Variables & Inputs + +- Hostnames, IP addresses, and cluster membership gathered from inventory or dynamically passed variables in playbooks. + +## Task Breakdown + +- Renders a hosts file compatible with /etc/hosts standards. +- Supports lab, demo, or production HA clusters with dynamic membership. + +## Dependencies & Relationships + +- Typically written by Ansible's copy/template module during node provisioning steps. + +## Output/Result diff --git a/olvm/docs/templates/ingress_security_rules.j2.md b/olvm/docs/templates/ingress_security_rules.j2.md new file mode 100644 index 0000000..389f79b --- /dev/null +++ b/olvm/docs/templates/ingress_security_rules.j2.md @@ -0,0 +1,25 @@ +# ingress_security_rules.j2 Documentation + +## Purpose & Overview + +Jinja2 YAML template listing default and feature-toggled ingress firewall/security rules for all VMs in Oracle Linux Virtualization Manager labs. + +## When to Use + +Use as include_vars or render target in security list configuration for initial node provisioning, or to expose HA, storage, and GUI ports in testbed and cluster builds. + +## Key Variables & Inputs + +- Feature toggles: opens additional ports for storage, HA, cluster, app, or remote desktop as required by scenario (variables in playbooks). +- Base rules always allow SSH (22/TCP). + +## Task Breakdown + +- Emits a structure under `instance_ingress_security_rules` with all baseline and optionally required ports (HTTPS, VNC, clustering, etc.). +- Fully YAML; no logic is executed here—behavior controlled externally. + +## Dependencies & Relationships + +- Consumed by create_instance.yml, create_vlan.yml, and any automation that manages network policy or OCI security lists. + +## Output/Result diff --git a/olvm/docs/templates/oci_vars.j2.md b/olvm/docs/templates/oci_vars.j2.md new file mode 100644 index 0000000..a13715b --- /dev/null +++ b/olvm/docs/templates/oci_vars.j2.md @@ -0,0 +1,26 @@ +# oci_vars.j2 Documentation + +## Purpose & Overview + +Jinja2 template to emit a YAML variable file with OCI resource references (compartment, VCN, subnet/subnet domain) for all downstream automation tasks and templates in OLVM. + +## When to Use + +Render as oci_vars.yml for use with template-driven resource creation, host configuration, and cluster automation pipelines where up-to-date cloud IDs are required for resource lookups or teardown. + +## Key Variables & Inputs + +- `my_compartment_id`, `my_vcn_id`, `my_subnet_id`, `my_subnet_domain_name` +- Driven by previous provisioning/tasks; injected at runtime by parent playbooks. + +## Task Breakdown + +- Outputs YAML mapping of current cloud state for robust automation by downstream roles. +- No logic, just substitution. + +## Dependencies & Relationships + +- Required by playbooks: build.yml, create_instance.yml, any task creating or cleaning up cloud resources. +- Maintains environment parity and enables Infrastructure as Code repeatability. + +## Output/Result diff --git a/olvm/docs/terminate_instance.md b/olvm/docs/terminate_instance.md new file mode 100644 index 0000000..e1a2320 --- /dev/null +++ b/olvm/docs/terminate_instance.md @@ -0,0 +1,27 @@ +# terminate_instance.yml Documentation + +## Purpose & Overview + +Safely destroys Oracle Linux Virtualization Manager lab compute/networking resources (instances, storage, networking), cleans up all artifacts after explicit user confirmation. + +## When to Use +Run when you wish to teardown the Oracle Linux Virtualization Manager lab environment and reclaim all OCI assets. Ensures a clean slate for future automation runs, infrastructure shifts, or migration events. + +## Key Variables & Inputs + +- State tracked with `.ansible-state` file. +- Uses default_vars.yml for context/config guidance. + +## Task Breakdown + +- Checks for state before performing any deletion (avoids accidental teardown). +- Deletes all OCI resources: instances, subnets, security lists, route tables, gateways, and VCNs. +- Prompts user to confirm all artifact and state file deletion (buffer, hosts, .ansible-state). +- Robust handling ensures no half-completed destruction. + +## Dependencies & Relationships + +- Should follow any infrastructure creation process, called explicitly or as a CI/CD teardown job. +- Ensures environment is fully reset for repeatable test/dev workflows. + +## Output/Result From 65dfd4216178eb9f30ed3634b8a8efd2ab489d1d Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Mon, 5 Jan 2026 11:19:42 +0000 Subject: [PATCH 07/10] Update the README files in the /Docs directory to improve consistency --- ocne/docs/README copy.md | 228 -------------------------------------- ocne/docs/README.md | 229 ++++++++++++++++++++++++++++++++++++++- ocne2/docs/README.md | 100 ++++++++--------- ol/docs/README.md | 2 +- olam/docs/README.md | 2 +- 5 files changed, 279 insertions(+), 282 deletions(-) delete mode 100644 ocne/docs/README copy.md diff --git a/ocne/docs/README copy.md b/ocne/docs/README copy.md deleted file mode 100644 index 4da2639..0000000 --- a/ocne/docs/README copy.md +++ /dev/null @@ -1,228 +0,0 @@ -# OCNE Automation Reference Documentation - -## 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 - -- [OCNE Automation Reference Documentation](#ocne-automation-reference-documentation) - - [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 | Launches OCI VM instances, networks, attaches storage and VNICs. | - | -| ceph_deployments.yml | 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 | 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 | 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 | Provisions OCI LB, configures health checks, backend set, exports LB IP to vars. | lb_vars.j2 | -| create_ocir.yml | Provisions OCI Container Registry and writes config for image integration. | ocir_vars.j2 | -| create_vlan.yml | Provisions VLAN in OCI/VCN and sets associated security groups. | - | -| default_vars.yml | Defines default topology, sizing, and feature toggles. | - | -| delete_fss.yml / delete_lb.yml / delete_ocir.yml | Teardown/removes FSS, Load Balancer, and Registry resources from OCI. | - | -| deploy_ocne_* | Orchestrate full OCNE cluster install (compact/full/quick/vlan/none). | myenvironment.j2 (in some flows) | -| fss_deployments.yml | 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 | Assigns static VLAN IPs and builds SSH trust for all nodes. | - | -| host_setup.yml | Sets up users, keys, directories, and enables passwordless SSH for automation. | - | -| ol8_repo_config.yml / ol9_repo_config.yml | Enables/disables YUM repos for OL8/OL9 and OLCNE install/update. | - | -| preconfig_oci_ccm.yml | Sets OCI CCM env variables in .bashrc for controller/cluster manager integration. | - | -| provision_istio.yml | Deploys Istio mesh module, renders and applies custom LB setup. | istio_lb.j2 | -| provision_kubectl.yml | Gives cluster users non-root access to kubectl, copying and exporting config. | - | -| provision_oci_ccm.yml | Deploys Oracle CCM for dynamic LB/service and cloud integration. | oci_vars.j2 | -| provision_ocne.yml | Manual path for full cluster install with conditional logic and config export. | myenvironment.j2 | - ---- - -## Jinja2 Templates - -| Template | Purpose / Usage | -| ------------------------- | ------------------------------------------------------------- | -| cluster.j2 | CephCluster CR (Rook/Ceph storage) | -| filesystem.j2 | CephFilesystem CR (CephFS persistence) | -| toolbox.j2 | Rook Ceph toolbox pod/deployment for CLI ops/troubleshooting | -| vm.j2 | KubeVirt VM manifest (K8s + OCI image + CephFS + cloud-init) | -| storageclass.j2 | StorageClass for dynamic CephFS PV provisioning (rook-cephfs) | -| pvc.j2 / fss_pvc.j2 | PVCs for CephFS (dynamic/static provisioning flows) | -| fss_pv.j2 | Static PersistentVolume for OCI FSS via CSI | -| fss_pod.j2 | Test/demo pod mounting the above PVC | -| fss_vars.j2 / oci_vars.j2 / lb_vars.j2 / ocir_vars.j2 | Dynamic YAML config/vars generated by playbooks | -| ingress_security_rules.j2 / egress_security_rules.j2 | Vars for security list rules in OCI, rendered by automation | -| istio_lb.j2 | OCI LB (internal, flex) setup for Istio Gateway | -| myenvironment.j2 | Master configuration file for `olcnectl` environment/module creation | - ---- - -## Tree Listing - -```markdown -|── ocne -    ├── build.md -    ├── ceph_deployments.md -    ├── create_fss.md -    ├── create_instance.md -    ├── create_lb.md -    ├── create_ocir.md -    ├── create_vlan.md -    ├── default_vars.md -    ├── delete_fss.md -    ├── delete_lb.md -    ├── delete_ocir.md -    ├── deploy_ocne_compact.md -    ├── deploy_ocne_full.md -    ├── deploy_ocne_none.md -    ├── deploy_ocne_quick.md -    ├── deploy_ocne_vlan.md -    ├── fss_deployments.md -    ├── host_assign_vlan_ip.md -    ├── host_setup.md -    ├── ol8_repo_config.md -    ├── ol9_repo_config.md -    ├── preconfig_oci_ccm.md -    ├── provision_istio.md -    ├── provision_kubectl.md -    ├── provision_oci_ccm.md -    ├── provision_ocne.md -    ├── pvc.j2.md -    ├── README copy.md -    ├── README.md -    └── templates -    ├── cluster.j2.md -    ├── egress_security_rules.j2.md -    ├── filesystem.j2.md -    ├── fss_pod.j2.md -    ├── fss_pv.j2.md -    ├── fss_pvc.j2.md -    ├── fss_vars.j2.md -    ├── ingress_security_rules.j2.md -    ├── istio_lb.j2.md -    ├── lb_vars.j2.md -    ├── myenvironment.j2.md -    ├── oci_vars.j2.md -    ├── ocir_vars.j2.md -    ├── storageclass.j2.md -    ├── toolbox.j2.md -    └── vm.j2.md -``` - ---- - -## 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/README.md b/ocne/docs/README.md index 880237e..9a4d2c5 100644 --- a/ocne/docs/README.md +++ b/ocne/docs/README.md @@ -1,3 +1,228 @@ -# README.md +# 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 | Launches OCI VM instances, networks, attaches storage and VNICs. | - | +| ceph_deployments.yml | 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 | 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 | 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 | Provisions OCI LB, configures health checks, backend set, exports LB IP to vars. | lb_vars.j2 | +| create_ocir.yml | Provisions OCI Container Registry and writes config for image integration. | ocir_vars.j2 | +| create_vlan.yml | Provisions VLAN in OCI/VCN and sets associated security groups. | - | +| default_vars.yml | Defines default topology, sizing, and feature toggles. | - | +| delete_fss.yml / delete_lb.yml / delete_ocir.yml | Teardown/removes FSS, Load Balancer, and Registry resources from OCI. | - | +| deploy_ocne_* | Orchestrate full OCNE cluster install (compact/full/quick/vlan/none). | myenvironment.j2 (in some flows) | +| fss_deployments.yml | 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 | Assigns static VLAN IPs and builds SSH trust for all nodes. | - | +| host_setup.yml | Sets up users, keys, directories, and enables passwordless SSH for automation. | - | +| ol8_repo_config.yml / ol9_repo_config.yml | Enables/disables YUM repos for OL8/OL9 and OLCNE install/update. | - | +| preconfig_oci_ccm.yml | Sets OCI CCM env variables in .bashrc for controller/cluster manager integration. | - | +| provision_istio.yml | Deploys Istio mesh module, renders and applies custom LB setup. | istio_lb.j2 | +| provision_kubectl.yml | Gives cluster users non-root access to kubectl, copying and exporting config. | - | +| provision_oci_ccm.yml | Deploys Oracle CCM for dynamic LB/service and cloud integration. | oci_vars.j2 | +| provision_ocne.yml | Manual path for full cluster install with conditional logic and config export. | myenvironment.j2 | + +--- + +## Jinja2 Templates + +| Template | Purpose / Usage | +| ------------------------- | ------------------------------------------------------------- | +| cluster.j2 | CephCluster CR (Rook/Ceph storage) | +| filesystem.j2 | CephFilesystem CR (CephFS persistence) | +| toolbox.j2 | Rook Ceph toolbox pod/deployment for CLI ops/troubleshooting | +| vm.j2 | KubeVirt VM manifest (K8s + OCI image + CephFS + cloud-init) | +| storageclass.j2 | StorageClass for dynamic CephFS PV provisioning (rook-cephfs) | +| pvc.j2 / fss_pvc.j2 | PVCs for CephFS (dynamic/static provisioning flows) | +| fss_pv.j2 | Static PersistentVolume for OCI FSS via CSI | +| fss_pod.j2 | Test/demo pod mounting the above PVC | +| fss_vars.j2 / oci_vars.j2 / lb_vars.j2 / ocir_vars.j2 | Dynamic YAML config/vars generated by playbooks | +| ingress_security_rules.j2 / egress_security_rules.j2 | Vars for security list rules in OCI, rendered by automation | +| istio_lb.j2 | OCI LB (internal, flex) setup for Istio Gateway | +| myenvironment.j2 | Master configuration file for `olcnectl` environment/module creation | + +--- + +## Tree Listing + +```markdown +|── ocne +    ├── build.md +    ├── ceph_deployments.md +    ├── create_fss.md +    ├── create_instance.md +    ├── create_lb.md +    ├── create_ocir.md +    ├── create_vlan.md +    ├── default_vars.md +    ├── delete_fss.md +    ├── delete_lb.md +    ├── delete_ocir.md +    ├── deploy_ocne_compact.md +    ├── deploy_ocne_full.md +    ├── deploy_ocne_none.md +    ├── deploy_ocne_quick.md +    ├── deploy_ocne_vlan.md +    ├── fss_deployments.md +    ├── host_assign_vlan_ip.md +    ├── host_setup.md +    ├── ol8_repo_config.md +    ├── ol9_repo_config.md +    ├── preconfig_oci_ccm.md +    ├── provision_istio.md +    ├── provision_kubectl.md +    ├── provision_oci_ccm.md +    ├── provision_ocne.md +    ├── pvc.j2.md +    ├── README copy.md +    ├── README.md +    └── templates +    ├── cluster.j2.md +    ├── egress_security_rules.j2.md +    ├── filesystem.j2.md +    ├── fss_pod.j2.md +    ├── fss_pv.j2.md +    ├── fss_pvc.j2.md +    ├── fss_vars.j2.md +    ├── ingress_security_rules.j2.md +    ├── istio_lb.j2.md +    ├── lb_vars.j2.md +    ├── myenvironment.j2.md +    ├── oci_vars.j2.md +    ├── ocir_vars.j2.md +    ├── storageclass.j2.md +    ├── toolbox.j2.md +    └── vm.j2.md +``` + +--- + +## 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/ocne2/docs/README.md b/ocne2/docs/README.md index 963ca1a..ff5f4a7 100644 --- a/ocne2/docs/README.md +++ b/ocne2/docs/README.md @@ -1,10 +1,12 @@ -# Deploy Oracle Cloud Native Environment +# Deploy Oracle Cloud Native Environment 2 ## Introduction Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for developing and managing cloud-native applications. The Kubernetes module is the core module. It deploys and manages containers and automatically installs and configures CRI-O, runC, and Kata Containers. CRI-O manages the container runtime for a Kubernetes cluster, which may be either runC or Kata Containers. -## Deploy Oracle CNE Using These Ansible Playbooks +--- + +## Deploy Oracle CNE 2 Using These Ansible Playbooks **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. @@ -69,29 +71,29 @@ Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for dev c. The default values (see `defaults.yml`) can be overridden by creating a separate file with the revised definition to be created. This example deploys an Oracle Linux 9 (`os_version: 9`) instance with 8 CPUs (`instance_ocpus: 8`) and 128Mb memory (`instance_memory: 128`) as well as increasing the boot volume size to be 256 Gb (`boot_volume_size_in_gbs: 256`). - d. Increase the Boot volume size, install libvirt, and use Oracle Linux 9. - - ```shell - cat << EOF | tee instances.yml > /dev/null - compute_instances: - 1: - instance_name: "ocne" - type: "server" - instance_ocpus: 8 - instance_memory: 128 - boot_volume_size_in_gbs: 256 - ocne_type: "libvirt" - install_ocne_rpm: true - update_all: true - os_version: "9" - EOF - ``` - - e. Deploy a single Oracle Linux 9 instance configured using the custom configuration created in `instances.yml`: - - ```shell - ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" - ``` + - i. Increase the Boot volume size, install libvirt, and use Oracle Linux 9. + + ```shell + cat << EOF | tee instances.yml > /dev/null + compute_instances: + 1: + instance_name: "ocne" + type: "server" + instance_ocpus: 8 + instance_memory: 128 + boot_volume_size_in_gbs: 256 + ocne_type: "libvirt" + install_ocne_rpm: true + update_all: true + os_version: "9" + EOF + ``` + + - ii. Deploy a single Oracle Linux 9 instance configured using the custom configuration created in `instances.yml`: + + ```shell + ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" + ``` **Note:** The free lab environment requires the extra variable `localhost_python_interpreter`, which sets `ansible_python_interpreter` for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules. Either remove, or update this variable to match your system's requirements. @@ -131,30 +133,29 @@ Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for dev ```markdown ├── ocne2 -│   ├── block.md -│   ├── build.md -│   ├── create_fss.md -│   ├── create_instance.md -│   ├── default_vars.md -│   ├── delete_fss.md -│   ├── deploy_ocne_libvirt.md -│   ├── deploy_ocne_none.md -│   ├── deploy_ocne_oci.md -│   ├── fss_deployments.md -│   ├── host_setup.md -│   ├── provision_podman.md -│   ├── README-Revised.md -│   ├── requirements.md -│   ├── templates -│   │   ├── egress_security_rules.j2.md -│   │   ├── fss_pod.j2.md -│   │   ├── fss_pv.j2.md -│   │   ├── fss_pvc.j2.md -│   │   ├── fss_vars.j2.md -│   │   ├── ingress_security_rules.j2.md -│   │   └── oci_vars.j2.md -│   └── update_all_rpms.md -└── README.md +    ├── block.md +    ├── build.md +    ├── create_fss.md +    ├── create_instance.md +    ├── default_vars.md +    ├── delete_fss.md +    ├── deploy_ocne_libvirt.md +    ├── deploy_ocne_none.md +    ├── deploy_ocne_oci.md +    ├── fss_deployments.md +    ├── host_setup.md +    ├── provision_podman.md +    ├── README-Revised.md +    ├── requirements.md + ├── update_all_rpms.md +    └── templates +       ├── egress_security_rules.j2.md +       ├── fss_pod.j2.md +       ├── fss_pv.j2.md +       ├── fss_pvc.j2.md +       ├── fss_vars.j2.md +       ├── ingress_security_rules.j2.md +       └── oci_vars.j2.md ``` --- @@ -190,4 +191,3 @@ Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for dev --- For troubleshooting, edge use cases, or advanced onboarding, see individual `.md` files in this directory. - diff --git a/ol/docs/README.md b/ol/docs/README.md index 9511882..98c46d6 100644 --- a/ol/docs/README.md +++ b/ol/docs/README.md @@ -1,4 +1,4 @@ -# Oracle Linux Lab Automation – Playbooks & Template Documentation +# Deploy Oracle Linux – Playbooks & Template Documentation ## Overview diff --git a/olam/docs/README.md b/olam/docs/README.md index 9d94c43..66c6fb3 100644 --- a/olam/docs/README.md +++ b/olam/docs/README.md @@ -1,4 +1,4 @@ -# Oracle Linux Automation Manager (OLAM) – Lab Playbook & Template Documentation +# Deploy Oracle Linux Automation Manager (OLAM) – Lab Playbook & Template Documentation ## Overview From db94e0575bb9c8ec9bd9e56a2935bf3784562b6d Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Tue, 6 Jan 2026 11:48:10 +0000 Subject: [PATCH 08/10] Update the README file in the OCNE Docs directory --- ocne/docs/README.md | 89 ++++++++++++++--------------- ocne/docs/{ => templates}/pvc.j2.md | 0 2 files changed, 44 insertions(+), 45 deletions(-) rename ocne/docs/{ => templates}/pvc.j2.md (100%) diff --git a/ocne/docs/README.md b/ocne/docs/README.md index 9a4d2c5..646b0e2 100644 --- a/ocne/docs/README.md +++ b/ocne/docs/README.md @@ -72,52 +72,51 @@ All documentation is auto-generated per playbook or template, providing comprehe ```markdown |── ocne -    ├── build.md -    ├── ceph_deployments.md -    ├── create_fss.md -    ├── create_instance.md -    ├── create_lb.md -    ├── create_ocir.md -    ├── create_vlan.md -    ├── default_vars.md -    ├── delete_fss.md -    ├── delete_lb.md -    ├── delete_ocir.md -    ├── deploy_ocne_compact.md -    ├── deploy_ocne_full.md -    ├── deploy_ocne_none.md -    ├── deploy_ocne_quick.md -    ├── deploy_ocne_vlan.md -    ├── fss_deployments.md -    ├── host_assign_vlan_ip.md -    ├── host_setup.md -    ├── ol8_repo_config.md -    ├── ol9_repo_config.md -    ├── preconfig_oci_ccm.md -    ├── provision_istio.md -    ├── provision_kubectl.md -    ├── provision_oci_ccm.md -    ├── provision_ocne.md -    ├── pvc.j2.md -    ├── README copy.md -    ├── README.md +    ├── 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 -    ├── egress_security_rules.j2.md -    ├── filesystem.j2.md -    ├── fss_pod.j2.md -    ├── fss_pv.j2.md -    ├── fss_pvc.j2.md -    ├── fss_vars.j2.md -    ├── ingress_security_rules.j2.md -    ├── istio_lb.j2.md -    ├── lb_vars.j2.md -    ├── myenvironment.j2.md -    ├── oci_vars.j2.md -    ├── ocir_vars.j2.md -    ├── storageclass.j2.md -    ├── toolbox.j2.md -    └── vm.j2.md +    ├── 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 ``` --- diff --git a/ocne/docs/pvc.j2.md b/ocne/docs/templates/pvc.j2.md similarity index 100% rename from ocne/docs/pvc.j2.md rename to ocne/docs/templates/pvc.j2.md From 84d9d0a20d8c8431cb2728d1cb4205e067c01f52 Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Wed, 7 Jan 2026 15:44:20 +0000 Subject: [PATCH 09/10] Update the README file in the OCNE and OCNE2 directories --- ocne/docs/README.md | 70 ++++++++++++++++++++++---------------------- ocne2/docs/README.md | 67 ++++++++++++++++++++++++------------------ 2 files changed, 73 insertions(+), 64 deletions(-) diff --git a/ocne/docs/README.md b/ocne/docs/README.md index 646b0e2..e6dfabf 100644 --- a/ocne/docs/README.md +++ b/ocne/docs/README.md @@ -25,46 +25,46 @@ All documentation is auto-generated per playbook or template, providing comprehe ## Playbooks -| Playbook | Summary | Related Templates / Files | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -| build.yml | Launches OCI VM instances, networks, attaches storage and VNICs. | - | -| ceph_deployments.yml | 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 | 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 | 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 | Provisions OCI LB, configures health checks, backend set, exports LB IP to vars. | lb_vars.j2 | -| create_ocir.yml | Provisions OCI Container Registry and writes config for image integration. | ocir_vars.j2 | -| create_vlan.yml | Provisions VLAN in OCI/VCN and sets associated security groups. | - | -| default_vars.yml | Defines default topology, sizing, and feature toggles. | - | -| delete_fss.yml / delete_lb.yml / delete_ocir.yml | Teardown/removes FSS, Load Balancer, and Registry resources from OCI. | - | -| deploy_ocne_* | Orchestrate full OCNE cluster install (compact/full/quick/vlan/none). | myenvironment.j2 (in some flows) | -| fss_deployments.yml | 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 | Assigns static VLAN IPs and builds SSH trust for all nodes. | - | -| host_setup.yml | Sets up users, keys, directories, and enables passwordless SSH for automation. | - | -| ol8_repo_config.yml / ol9_repo_config.yml | Enables/disables YUM repos for OL8/OL9 and OLCNE install/update. | - | -| preconfig_oci_ccm.yml | Sets OCI CCM env variables in .bashrc for controller/cluster manager integration. | - | -| provision_istio.yml | Deploys Istio mesh module, renders and applies custom LB setup. | istio_lb.j2 | -| provision_kubectl.yml | Gives cluster users non-root access to kubectl, copying and exporting config. | - | -| provision_oci_ccm.yml | Deploys Oracle CCM for dynamic LB/service and cloud integration. | oci_vars.j2 | -| provision_ocne.yml | Manual path for full cluster install with conditional logic and config export. | myenvironment.j2 | +| 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 | CephCluster CR (Rook/Ceph storage) | -| filesystem.j2 | CephFilesystem CR (CephFS persistence) | -| toolbox.j2 | Rook Ceph toolbox pod/deployment for CLI ops/troubleshooting | -| vm.j2 | KubeVirt VM manifest (K8s + OCI image + CephFS + cloud-init) | -| storageclass.j2 | StorageClass for dynamic CephFS PV provisioning (rook-cephfs) | -| pvc.j2 / fss_pvc.j2 | PVCs for CephFS (dynamic/static provisioning flows) | -| fss_pv.j2 | Static PersistentVolume for OCI FSS via CSI | -| fss_pod.j2 | Test/demo pod mounting the above PVC | -| fss_vars.j2 / oci_vars.j2 / lb_vars.j2 / ocir_vars.j2 | Dynamic YAML config/vars generated by playbooks | -| ingress_security_rules.j2 / egress_security_rules.j2 | Vars for security list rules in OCI, rendered by automation | -| istio_lb.j2 | OCI LB (internal, flex) setup for Istio Gateway | -| myenvironment.j2 | Master configuration file for `olcnectl` environment/module creation | +| 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 | --- diff --git a/ocne2/docs/README.md b/ocne2/docs/README.md index ff5f4a7..9c7d35f 100644 --- a/ocne2/docs/README.md +++ b/ocne2/docs/README.md @@ -121,41 +121,50 @@ Oracle Cloud Native Environment (Oracle CNE) is a fully integrated suite for dev | [provision_podman.md](./provision_podmam.md) | Install Podman and container tools for OCI/Linux | | [requirements.md](./requirements.md) | Ansible Galaxy collections needed for all playbooks | | [update_all_rpms.md](./update_all_rpms.md) | Update all OS packages and reboot as needed | -| [templates/egress_security_rules.j2.md](./templates/egress_security_reules.j2.md) | Jinja2 template for outbound network security rules (exported as YAML var file) | -| [templates/ingress_security_rules.j2.md](./templates/ingress_security_rules.j2.md) | Jinja2 template for inbound network security rules (exported as YAML var file) | -| [templates/fss_pv.j2.md](./templates/fss_pv.j2.md) | Template for Kubernetes PersistentVolume integrating OCI FSS. | -| [templates/fss_pvc.j2.md](./templates/fss_pvc.j2.md) | Template for Kubernetes PersistentVolumeClaim (PVC) for FSS | -| [templates/fss_pod.j2.md](./templates/fss_pod.j2.md) | Template for sample/test K8s Pod using the FSS PVC | -| [templates/fss_vars.j2.md](./templates/fss_vars.j2.md) | Template for storing FSS variable output during provisioning | -| [templates/oci_vars.j2.md](./templates/oci_vars.j2.md) | Template for storing key OCI variables as a YAML snippet | + +--- + +## Jinja2 Templates + +| Template | Purpose / Usage | +| --- | --- | +| [egress_security_rules.j2.md](./templates/egress_security_reules.j2.md) | Jinja2 template for outbound network security rules (exported as YAML var file) | +| [ingress_security_rules.j2.md](./templates/ingress_security_rules.j2.md) | Jinja2 template for inbound network security rules (exported as YAML var file) | +| [fss_pv.j2.md](./templates/fss_pv.j2.md) | Template for Kubernetes PersistentVolume integrating OCI FSS. | +| [fss_pvc.j2.md](./templates/fss_pvc.j2.md) | Template for Kubernetes PersistentVolumeClaim (PVC) for FSS | +| [fss_pod.j2.md](./templates/fss_pod.j2.md) | Template for sample/test K8s Pod using the FSS PVC | +| [fss_vars.j2.md](./templates/fss_vars.j2.md) | Template for storing FSS variable output during provisioning | +| [oci_vars.j2.md](./templates/oci_vars.j2.md) | Template for storing key OCI variables as a YAML snippet | + +--- ## Tree Listing ```markdown ├── ocne2 -    ├── block.md -    ├── build.md -    ├── create_fss.md -    ├── create_instance.md -    ├── default_vars.md -    ├── delete_fss.md -    ├── deploy_ocne_libvirt.md -    ├── deploy_ocne_none.md -    ├── deploy_ocne_oci.md -    ├── fss_deployments.md -    ├── host_setup.md -    ├── provision_podman.md -    ├── README-Revised.md -    ├── requirements.md - ├── update_all_rpms.md +    ├── block.md # Add block storage (volumes) to OCI compute instances +    ├── build.md # Launch and configure compute instances in OCI +    ├── create_fss.md # Provision OCI File Storage Service (FSS) components +    ├── create_instance.md # Main Orchestration Playbook: Provisions all resources and runs end-to-end lab automation +    ├── default_vars.md # Defines structure, sizing, cluster, user, and feature toggle variables used by all playbooks. +    ├── delete_fss.md # Teardown (delete) FSS components cleanly +    ├── deploy_ocne_libvirt.md # Deploy Oracle CNE cluster on local KVM/Libvirt +    ├── deploy_ocne_none.md # Configures an OCI Instance ready to Deploy Oracle CNE cluster +    ├── deploy_ocne_oci.md # Deploy Oracle CNE cluster directly on OCI infrastructure +    ├── fss_deployments.md # Generates Kubernetes manifests for FSS-backed PersistentVolume/Pod +    ├── host_setup.md # Prepares OS/user/SSH/facts on each instance +    ├── provision_podman.md # Install Podman and container tools for OCI/Linux +    ├── README.md # This File +    ├── requirements.md # Ansible Galaxy collections needed for all playbooks + ├── update_all_rpms.md # Update all OS packages and reboot as needed    └── templates -       ├── egress_security_rules.j2.md -       ├── fss_pod.j2.md -       ├── fss_pv.j2.md -       ├── fss_pvc.j2.md -       ├── fss_vars.j2.md -       ├── ingress_security_rules.j2.md -       └── oci_vars.j2.md +       ├── egress_security_rules.j2.md # Jinja2 template for outbound network security rules (exported as YAML var file) +       ├── fss_pod.j2.md # Template for sample/test K8s Pod using the FSS PVC +       ├── fss_pv.j2.md # Template for Kubernetes PersistentVolume integrating OCI FSS. +       ├── fss_pvc.j2.md # Template for Kubernetes PersistentVolumeClaim (PVC) for FSS +       ├── fss_vars.j2.md # Template for storing FSS variable output during provisioning +       ├── ingress_security_rules.j2.md # Jinja2 template for inbound network security rules (exported as YAML var file) +       └── oci_vars.j2.md # Template for storing key OCI variables as a YAML snippet ``` --- From d2b6147bf1627317d02839a867a0b80a10ae6746 Mon Sep 17 00:00:00 2001 From: Martin Littlecott Date: Fri, 9 Jan 2026 11:47:23 +0000 Subject: [PATCH 10/10] Update the README file in the OL, OLAM and OLVM directories --- ol/docs/README.md | 40 ++++++++++++------------ olam/docs/README.md | 76 ++++++++++++++++++++++----------------------- olvm/docs/README.md | 65 +++++++++++++++++++------------------- 3 files changed, 91 insertions(+), 90 deletions(-) diff --git a/ol/docs/README.md b/ol/docs/README.md index 98c46d6..e1c65f5 100644 --- a/ol/docs/README.md +++ b/ol/docs/README.md @@ -97,7 +97,7 @@ You’ll find an individual Markdown (`.md`) doc for each playbook or template, | - | - | - | | [block.yml](./block.md) | Provisions and attaches OCI block storage volumes to instances. | Used by build.yml & create_instance.yml | | [build.yml](./build.md) | Automates compute instance launch & storage, inventories hosts. | block.yml | -| [create_instance.yml](./create_instance.md) | Top-level orchestrator: provisions network, VMs, SSH, and teardown | All major plays/templates | +| [create_instance.yml](./create_instance.md) | Top-level orchestrator: provisions network, Virtual Machines (VMs), SSH, and teardown | All major plays/templates | | [default_vars.yml](./default_vars.md) | Central variable set for all hosts, provisioning, toggles. | Included everywhere | | [download_ol_iso.yml](./download_ol_iso.md) | Automates Oracle Linux ISO downloads for local builds. | | | [host_setup.yml](./host_setup.md) | Prepares hosts: users, SSH, sudo, locale, retry-on-fail. | | @@ -125,26 +125,26 @@ You’ll find an individual Markdown (`.md`) doc for each playbook or template, ```markdown └-─ ol -    ├── block.md -    ├── build.md -    ├── create_instance.md -    ├── default_vars.md -    ├── download_ol_iso.md -    ├── host_setup.md -    ├── passwordless_setup.md -    ├── provision_kvm_vm.md -    ├── provision_kvm.md -    ├── provision_podman.md -    ├── provision_vbox.md -    ├── provision_vnc.md -    ├── README.md -    ├── requirements.md - ├── update_all_rpms.md +    ├── block.md # Provisions and attaches OCI block storage volumes to instances. +    ├── build.md # Automates compute instance launch & storage, inventories hosts. +    ├── create_instance.md # Top-level orchestrator: provisions network, Virtual Machines (VMs), SSH, and teardown. +    ├── default_vars.md # Central variable set for all hosts, provisioning, toggles. +    ├── download_ol_iso.md # Automates Oracle Linux ISO downloads for local builds. +    ├── host_setup.md # Prepares hosts: users, SSH, sudo, locale, retry-on-fail. +    ├── passwordless_setup.md # Ensures password-less SSH between all hosts. +    ├── provision_kvm_vm.md # Provisions/reconfigures KVM VMs by pulling images, defining VMs. +    ├── provision_kvm.md # Installs/configures KVM hypervisor, delegates to `provision_kvm_vm.yml`. +    ├── provision_podman.md # Installs Podman/containers, OL8/9+ variant support. +    ├── provision_vbox.md # Sets up Oracle VirtualBox, repo, keys, and extpack. +    ├── provision_vnc.md # Enables TigerVNC/graphical login for remote desktop access. +    ├── README.md # This File. +    ├── requirements.md # Tracks required Galaxy collections for roles/modules. + ├── update_all_rpms.md # Automates dnf update for all packages, safe kernel reboot.    └── templates -       ├── egress_security_rules.j2.md -       ├── ingress_security_rules.j2.md -       ├── oci_vars.j2.md -       └── vm_template.j2.md +       ├── egress_security_rules.j2.md # Default egress: allow all TCP outbound. +       ├── ingress_security_rules.j2.md # Conditional ingress rules for all services (SSH, Nginx, NFS, etc.). +       ├── oci_vars.j2.md # Emits OCI resource IDs for automation. +       └── vm_template.j2.md # Parameterized libvirt/KVM XML template for VMs. ``` --- diff --git a/olam/docs/README.md b/olam/docs/README.md index 66c6fb3..6be86cd 100644 --- a/olam/docs/README.md +++ b/olam/docs/README.md @@ -121,45 +121,45 @@ This directory contains authoritative, onboarding-focused documentation for ever ```markdown └── olam -    ├── block.md -    ├── build.md -    ├── check_instance_available.md -    ├── configure_passwordless_ssh.md -    ├── convert_ansible_inventory.sh.md -    ├── create_instance.md -    ├── default_vars.md -    ├── deploy_olam_cluster.md -    ├── deploy_olam_none.md -    ├── deploy_olam_olae.md -    ├── deploy_olam_single.md -    ├── deploy_olam_v1.md -    ├── get_facts.md -    ├── provision_builder.md -    ├── provision_free_ipa.md -    ├── provision_git_server.md -    ├── provision_instance_basics.md -    ├── provision_kvm.md -    ├── provision_pah.md -    ├── provision_vnc.md -    ├── README.md -    ├── requirements.md -    ├── terminate_instance.md -    ├── update_all_rpms.md +    ├── block.md # Attaches OCI block storage volumes to compute nodes. +    ├── build.md # Launch and inventory OCI instances, configures storage/net. +    ├── check_instance_available.md # Sanity and reachability check for lab/OCI hosts. +    ├── configure_passwordless_ssh.md # Sets up password-less SSH trust between all hosts. +    ├── convert_ansible_inventory.sh.md # Converts nonstandard Ansible inventories to clustered format. +    ├── create_instance.md # Top-level orchestrator: bootstraps all infra, Oracle Linux Automation Manager, teardown. +    ├── default_vars.md # All central configuration: VM sizing, features, credentials. +    ├── deploy_olam_cluster.md # Multi-node Oracle Linux Automation Manager cluster install (control/execution/db nodes). +    ├── deploy_olam_none.md # No-op for conditional disables or dry-runs. +    ├── deploy_olam_olae.md # Installs ansible-core for basic OLAE only test/dev setups. +    ├── deploy_olam_single.md # Single-control-node Oracle Linux Automation Manager deployment for quickstart/testing. +    ├── deploy_olam_v1.md # Deploys legacy (v1) Oracle Linux Automation Manager for migration/compatibility. +    ├── get_facts.md # Minimal fact gathering utility, prints localhost info. +    ├── provision_builder.md # Builds custom Ansible Builder Execution Environments (EE). +    ├── provision_free_ipa.md # Sets up FreeIPA for SSO/directory integration via role. +    ├── provision_git_server.md # Bootstraps a git server and creates initial repo. +    ├── provision_instance_basics.md # Ensures all base users, SSH, tags, and locales are ready. +    ├── provision_kvm.md # Installs KVM/libvirt/cockpit for in-lab virtualization. +    ├── provision_pah.md # Sets up Private Automation Hub (PAH) for collection sharing. +    ├── provision_vnc.md # Installs VNC/GUI on devops-node(s) for remote graphical login. +    ├── README.md # This file. +    ├── requirements.md # Lists all Ansible Galaxy collection requirements. +    ├── terminate_instance.md # Deletes OCI lab VMs/resources and prompts for artifact wipe. +    ├── update_all_rpms.md # Updates all packages, reboots lab hosts as needed.   └── templates -       ├── bindep.txt.j2.md -       ├── egress_security_rules.j2.md -       ├── execution_environment.yml.j2.md -       ├── hosts.j2.md -       ├── ingress_security_rules.j2.md -       ├── install_ipa.j2.md -       ├── nginx.conf_v1.j2.md -       ├── nginx.conf.j2.md -       ├── oci_vars.j2.md -       ├── playbook.yml.j2.md -       ├── receptor_cluster.conf.j2.md -       ├── receptor.conf.j2.md -       ├── requirements.txt.j2.md -       └── requirements.yml.j2.md +       ├── bindep.txt.j2.md # Build/package dependencies for Execution Environments. +      ├── egress_security_rules.j2.md # OCI security rule: enables all TCP egress. +       ├── execution_environment.yml.j2.md # Ansible Builder EE build context/dependencies. +       ├── hosts.j2.md # Ansible inventory for PAH/single-host setups. +       ├── ingress_security_rules.j2.md # Dynamic ingress rules for OCI security—feature toggled. +       ├── install_ipa.j2.md # Shell install script for FreeIPA server. +       ├── nginx.conf_v1.j2.md # Base Nginx config, feature toggled server blocks. +       ├── nginx.conf.j2.md # Base Nginx config, feature toggled server blocks. +       ├── oci_vars.j2.md # Core OCID variables for templates and automation. +       ├── playbook.yml.j2.md # Sample EE task playbook: gets OCI storage namespace. +       ├── receptor_cluster.conf.j2.md # Config for multi-node receptor mesh (lab HA/cluster). +       ├── receptor.conf.j2.md # Single node receptor config, group logic. +       ├── requirements.txt.j2.md # Python (pip) requirements for EEs. +       └── requirements.yml.j2.md # Galaxy collection requirements for EEs. ``` --- diff --git a/olvm/docs/README.md b/olvm/docs/README.md index fadc270..89e9ffc 100644 --- a/olvm/docs/README.md +++ b/olvm/docs/README.md @@ -4,12 +4,12 @@ This directory provides detailed documentation for every Ansible playbook and Jinja2 template found in `linux-virt-labs/olvm/`. -- Each lab file is mapped 1:1 to a Markdown (`.md`) doc for rapid navigation, debugging, and advanced scenario-building. +- Each file is mapped 1:1 to a Markdown (`.md`) doc for rapid navigation, debugging, and advanced scenario-building. - Use this index to onboard, extend, or troubleshoot end-to-end Oracle Linux Virtualization Manager cluster/lab automation. --- -## Deploy Oracle Linux Virtualization Manager Using These Ansible Playbooks + ## Documentation Table @@ -128,36 +128,37 @@ This directory provides detailed documentation for every Ansible playbook and Ji ```markdown └── olvm - ├── build.md - ├── check_instance_available.md - ├── configure_passwordless_ssh.md - ├── configure_secondary_nic.md - ├── create_block_storage.md - ├── create_hostfile_secondary_nic.md - ├── create_vlan.md - ├── default_vars.md - ├── ovirt_add_hosts.md - ├── ovirt_add_logical_network.md - ├── ovirt_add_storage_domain.md - ├── ovirt_check_hosts.md - ├── ovirt_connection_test.md - ├── ovirt_create_vm_from_template.md - ├── ovirt_delete_host.md - ├── ovirt_import_template.md - ├── ovirt_list_hosts.md - ├── provision_instance_basics.md - ├── provision_olvm_engine_publickey.md - ├── provision_olvm_engine.md - ├── provision_vnc.md - ├── README.md - ├── requirements.md - ├── terminate_instance.md + ├── build.md # Provisions OCI compute instances, VNICs, VLAN, block storage. + ├── check_instance_available.md # Connectivity/fact check for all engine/KVM hosts. + ├── configure_passwordless_ssh.md # Sets up SSH trust between all engine/KVM hosts. + ├── configure_secondary_nic.md # Configures secondary NICs on engine/KVM hosts for cluster/storage. + ├── create_block_storage.md # Attaches OCI block storage to VMs for storage domains. + ├── create_hostfile_secondary_nic.md # Writes secondary NIC hosts aliasing for KVM/engine. + ├── create_instance.md # Top-level cluster orchestrator—bootstraps infra, nodes, overlay net, etc. + ├── create_vlan.md # Provisions VLAN & NSG for advanced networking. + ├── default_vars.md # Variables for all KVM, engine, storage, and cluster config. + ├── ovirt_add_hosts.md # Adds KVM hosts to the Oracle Linux Virtualization Manager/oVirt engine/cluster. + ├── ovirt_add_logical_network.md # Adds logical network to Oracle Linux Virtualization Manager cluster for segmentation/testing. + ├── ovirt_add_storage_domain.md # Adds storage domains for VMs and ISO images. + ├── ovirt_check_hosts.md # Verifies KVM/oVirt hosts are online, ready, and registered. + ├── ovirt_connection_test.md # Tests connection/auth to Oracle Linux Virtualization Manager engine before further steps. + ├── ovirt_create_vm_from_template.md # Creates VMs from pre-imported templates. + ├── ovirt_delete_host.md # Removes KVM hosts from the cluster and decommissions. + ├── ovirt_import_template.md # Imports VM/OVA templates to cluster storage domains. + ├── ovirt_list_hosts.md # Lists all available KVM/oVirt hosts in the cluster. + ├── provision_instance_basics.md # Core user/SSH/locale prep for all hosts. + ├── provision_olvm_engine_publickey.md # Copies engine pubkey to KVM hosts for trust. + ├── provision_olvm_engine.md # Configures Oracle Linux Virtualization Manager engine & exposes host/cluster for control plane. + ├── provision_vnc.md # Adds VNC/GUI capability to engine nodes in the lab. + ├── README.md # This file. + ├── requirements.md # Ansible Galaxy collection dependencies for cluster automation. + ├── terminate_instance.md # Fully tears down OCI and resets all resource state. └── templates -    ├── answer_file.j2.md -    ├── egress_security_rules.j2.md -    ├── etc_hosts_kvm.j2.md -    ├── ingress_security_rules.j2.md -    └── oci_vars.j2.md +    ├── answer_file.j2.md # Automated installer answers for unattended setups. +    ├── egress_security_rules.j2.md # YAML variable: allows all TCP traffic from VMs. +    ├── etc_hosts_kvm.j2.md # Generates /etc/hosts entries for secondary-NIC HA labs. +    ├── ingress_security_rules.j2.md # YAML variable: allows feature-based ports per scenario. +    └── oci_vars.j2.md # Core OCI resource mapping file for automated flows. ``` ---