Podman-first Docs + CI Overhaul: EE Build, Docs Site, and Pages Deploy - #3
Open
tosin2013 wants to merge 38 commits into
Open
Podman-first Docs + CI Overhaul: EE Build, Docs Site, and Pages Deploy#3tosin2013 wants to merge 38 commits into
tosin2013 wants to merge 38 commits into
Conversation
- Add AGENTS.md with repo-specific contributor guidelines - Podman-first CI: build-and-push to Quay workflow - Add docs build workflow with mkdocs --strict - Create CI/CD, llms.txt, and local docs how-to guides - Refactor advanced usage into task-oriented format - Add internal link checks and fix MkDocs nav - README: link to docs; clarify Podman usage - Add local docs test script and Makefile targets - Update mkdocs config paths; ignore site/ and .venv-docs
…ub Pages fix: update site URL in mkdocs configuration
…ooling - Introduced a new guide on enabling Kubernetes and OpenShift tooling in the Execution Environment (EE), detailing two installation paths (RPM and tarball). - Created a troubleshooting guide for common EE build errors and their fixes. - Updated the index and navigation structure to include new guides and references. - Added a reference document for `execution-environment.yml`, outlining best practices and field descriptions. - Included a reference for Makefile targets and environment variables. - Established a policy document (`llms.txt`) for LLM usage preferences. - Enhanced the `execution-environment.yml` to support OpenShift client installations via RHSM and tarball methods. - Implemented scripts for managing package installations and dependencies, filtering out unnecessary packages. - Updated requirements to reflect changes in dependencies and collections.
- Add Makefile targets for Path A (RHSM) and Path B (Tarball) builds - Create test-openshift-tooling.sh script to verify oc/kubectl installation - Split GitHub Actions into three separate workflows: * test-openshift-tarball.yml: Tests Path B (tarball install) * test-openshift-rhsm.yml: Tests Path A (RHSM/RPM install) * test-baseline.yml: Tests baseline EE without OpenShift tooling - Update documentation to clarify collections are optional - Ensure binary installation works independently of Ansible collections This ensures consistent, isolated testing of both installation paths and validates that oc/kubectl binaries work independently of kubernetes.core/redhat.openshift collections.
GitHub Actions workflows require 'on:' without quotes, not ''on'':. This fixes YAML syntax errors that prevented workflows from running.
…nditions
Changed 'if: ${{ secrets.VAR && secrets.VAR2 }}' to
'if: ${{ secrets.VAR != "" && secrets.VAR2 != "" }}'
This uses the proper syntax for checking if secrets exist in GitHub Actions.
Changed from job-level 'if: ${{ secrets.RH_ORG != "" && secrets.RH_ACT_KEY != "" }}'
to step-level check that sets an output variable.
This avoids the GitHub Actions limitation where secrets cannot be directly
referenced in job-level if conditions. All steps now check the output variable
and skip gracefully if credentials are missing.
Added a new workflow that uses the GitHub Action Validator action to automatically validate all workflows in .github/workflows/ on: - Push to main branch - Pull requests modifying workflow files - Manual workflow dispatch This ensures all workflows are syntactically valid before they run. Reference: https://github.com/marketplace/actions/github-action-validator
Created scripts/login-registry.sh for secure and reusable registry login. Updated all workflows to use the shell script instead of inline commands. Benefits: - Better error handling and validation - Reusable across workflows - Cleaner workflow definitions - Safer credential handling - Easy to test independently The script: - Checks if container engine is available - Validates credentials are provided - Handles login failures gracefully - Works with podman or docker
Changed from referencing secrets directly in step-level if condition to using job-level environment variables. This avoids the GitHub Actions limitation where secrets cannot be directly referenced in step-level if conditions after a job-level if has been used. Now uses env.REDHAT_REGISTRY_USERNAME and env.REDHAT_REGISTRY_PASSWORD instead of secrets.REDHAT_REGISTRY_USERNAME and secrets.REDHAT_REGISTRY_PASSWORD in the step condition.
Changed from referencing secrets directly in if condition to using job-level environment variables. This avoids the GitHub Actions limitation where secrets cannot be directly referenced in if conditions. Now uses env.REDHAT_REGISTRY_USERNAME and env.REDHAT_REGISTRY_PASSWORD instead of secrets.REDHAT_REGISTRY_USERNAME and secrets.REDHAT_REGISTRY_PASSWORD.
…-tarball Changed from referencing secrets directly in if condition to using global-level environment variables. This avoids the GitHub Actions limitation where secrets cannot be directly referenced in if conditions. Now uses env.REDHAT_REGISTRY_USERNAME and env.REDHAT_REGISTRY_PASSWORD instead of secrets.REDHAT_REGISTRY_USERNAME and secrets.REDHAT_REGISTRY_PASSWORD.
Changed from referencing secrets directly in if condition to using global-level environment variables. This avoids the GitHub Actions limitation where secrets cannot be directly referenced in if conditions.
Changed from rhocp-4.15/4.14 to rhocp-4.18/4.17 to align with RHEL 9.6's supported OpenShift versions. Path A (RHSM) will now: • Try to enable rhocp-4.18-for-rhel-9 repo first • Fall back to rhocp-4.17-for-rhel-9 if 4.18 not available This ensures the OpenShift client tools match the system architecture and RHEL 9.6's officially supported versions.
Added support for overriding TARGET_HUB, TARGET_NAME, and TARGET_TAG via: 1. GitHub secrets (recommended for CI/CD) 2. Environment variables (for local development) 3. Makefile defaults (fallback) Maintainers can now easily customize the registry/image name by: - Setting GitHub secrets: TARGET_HUB, TARGET_NAME, TARGET_TAG - Or using environment variables: export TARGET_HUB=quay.io - Or passing to make: TARGET_HUB=quay.io TARGET_NAME=org/repo make build This enables forks to have their own registry without modifying code.
Added 'Determine Target Tag' step that computes image tag dynamically: • Git tags (e.g., v5, v6): Use the tag as image tag (v5 → v5) • Main branch: Use 'latest' tag • Other branches/PRs: Use branch name (feature-x → feature-x) This enables: - Automatic releases when pushing git tags - 'latest' image on main branch - Development images on feature branches - No need to manually set TARGET_TAG in secrets Example: • git tag v5 && git push --tags → builds quay.io/org/repo:v5 • git push to main → builds quay.io/org/repo:latest • git push to feature branch → builds quay.io/org/repo:feature-name
Removed duplicate 'env' definition in 'Log in to registry.redhat.io' step that was causing YAML validation error.
Changed OC_VERSION from 'stable-4.19' to 'v4.19' to match the correct tarball mirror URL path at: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/v4.19/openshift-client-linux.tar.gz The 'stable-4.19' format does not resolve to a valid path on the mirror. Using 'v4.19' ensures curl can successfully download the tarball during the build process. Path B (Tarball) tests will now correctly download and install oc/kubectl.
Added verbose logging to diagnose tarball download and extraction issues: • Log OC_VERSION and OC_URL variables • Show final constructed URL • Use curl -v for verbose download output • Log extraction and permission changes • Verify installation immediately after This helps troubleshoot failures in Path B (Tarball) installation.
The tarball mirror requires specific release versions (e.g., v4.19.0), not generic versions (v4.19). The URL 'v4.19' returned HTTP 404. Changed OC_VERSION from 'v4.19' to 'v4.19.0' in: - Makefile setup-openshift-tarball target - .github/workflows/test-openshift-tarball.yml setup step This ensures the curl command downloads from a valid mirror path: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/v4.19.0/openshift-client-linux.tar.gz
Instead of pinning to a specific version (v4.19.0), use 'latest-4.19' which: • Automatically uses the newest 4.19.x release • Simplifies maintenance (no need to update version strings) • Aligns with recommended OpenShift practices • Works with the OpenShift mirror structure The URL structure leverages the mirror's 'latest-X.Y' directories: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest-4.19/openshift-client-linux.tar.gz This ensures we always get the latest stable 4.19 release.
The base image (ee-minimal-rhel9:latest) comes with ansible-core 2.16.14 installed via RPM. Pip cannot uninstall or downgrade RPM-managed packages. Changed from ansible-core==2.15.13 to ansible-core==2.16.14 to match the base image version, avoiding the pip uninstall error. This allows the build to complete successfully while keeping the same Ansible functionality.
The base image (ee-minimal-rhel9:latest) already includes ansible-core via RPM. Specifying it in pip requirements causes conflicts: • ansible-core==2.15.13 tries to downgrade the RPM version • ansible-core==2.16.14 doesn't exist on PyPI Solution: Remove ansible_core from dependencies since it's already provided by the base image. Keep ansible-runner which is genuinely needed for ansible-builder functionality.
The venv creation fails when there are no ansible packages to install because pip is not bootstrapped. Using >=2.15.13 allows pip to: 1. Install 2.15.13 if the RPM version is in conflict 2. Skip installation if a compatible version exists 3. Properly bootstrap pip in the venv This ensures the venv is properly initialized while avoiding forced reinstalls of RPM-managed packages.
The venv is created with --without-pip. When ansible-core>=2.15.13 might be satisfied by the RPM version, pip never gets invoked to bootstrap the venv. This causes 'No module named pip' error during the assemble step. Solution: Explicitly install pip and setuptools in requirements.txt to ensure the venv is properly initialized regardless of RPM package states.
Path A (RHSM): Uncomment kubernetes.core and redhat.openshift collections - RHSM enables the repos needed by these collections - Tests both binaries AND Ansible collections Path B (Tarball): Keep collections commented - Tarball install only provides oc/kubectl binaries - Collections are optional, no repos available - Tests binary installation only Each workflow now properly manages the requirements.yml collections to match the specific testing path requirements.
…licts The base image comes with curl-minimal which conflicts with curl. When installing curl for the tarball download, microdnf fails with: 'package curl-minimal conflicts with curl' Solution: Explicitly remove curl-minimal first before installing curl. This avoids the package dependency conflict and ensures curl is available for downloading the OpenShift tarball.
tosin2013
force-pushed
the
main
branch
2 times, most recently
from
November 3, 2025 15:49
410ef8b to
f0ae948
Compare
- Add 'make setup' target to verify development environment setup - Detects OS and Python version - Checks for required tools (podman, git, jq, etc.) - Provides RHEL-specific installation instructions for ansible-navigator - Supports Python 3.10+ detection and recommendations - Improves build output visibility with status messages - Fix 'No module named pip' build error - Add python3-pip to files/bindep.txt system dependencies - Ensures pip is installed during build process - Resolves issue with minimal base image lacking pip - Update troubleshooting documentation - Add section for 'No module named pip' error - Include Red Hat Solution 7116301 reference - Document root cause and fix for pip installation issue - Improve build target - Better registry login handling with fallback options - Enhanced output visibility with status messages - All output shown in real-time via tee commands
- Prevents ansible-navigator from trying to pull image from registry - Uses locally built image instead of attempting remote pull - Fixes 'localhost registry connection refused' error during make test - Ensures CI/CD workflows use correct locally built image
- Replace parse-time token check with execution-time validation - Create check-token target that only runs when needed - Allows targets like 'test', 'setup', 'lint' to run without token - Fixes GitHub Actions workflows where test runs after build - Token only required for build and token targets that need it
- Add --pull-policy never to ansible-navigator commands in test script - Ensures test uses locally built image instead of pulling - Prevents registry connection errors during testing
- Replace 'which' command with 'test -f' for binary detection - 'which' is not available in minimal base images - Check common locations (/usr/local/bin and /usr/bin) - Add symlinks from /usr/local/bin to /usr/bin for oc/kubectl - Improves compatibility with Ansible modules - Ensures binaries are found in standard /usr/bin location - Fixes test-openshift-tooling script to work with minimal images
- Add 'make setup' to getting started guide and quick reference - Document new setup target with detailed capabilities - Add Key Insights section to main documentation index - Update make-targets reference with setup target and insights - Enhance troubleshooting guide with common pitfalls section - Update build-locally guide with setup recommendations - Add insights about token requirements (execution-time checks) - Document Python 3.10+ requirement and RHEL-specific instructions - Add note about python3-pip requirement in bindep.txt - Document pull-policy never behavior for test targets - Add insights about minimal image limitations (which command) - Update OpenShift guide with symlink and test-f compatibility notes - Add Quick Reference section for new users with common issues All updates based on actual findings from: - Development environment setup validation - Pip installation troubleshooting - Token check improvements - Image pull policy fixes - OpenShift tooling compatibility improvements
Owner
|
Hi @tosin2013 ,
I'm also working on a branch that will do the following:
Additionally, your |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updated this repository for the Red Hat ecosystem with Podman-first workflows, a structured documentation site (MkDocs + Material), and GitHub Actions for building EEs and deploying docs to GitHub Pages. Adds a concise contributor guide (AGENTS.md) and fixes internal links and YAML lint warnings.
Key Changes
AGENTS.mdwith project structure, Make targets, style, PR rules.docs/(Diátaxis),mkdocs.yml/mkdocs.yml, and local build guide..github/workflows/build-and-push.ymlbuilds/tests EE, pushes to Quay..github/workflows/docs-build.ymlbuilds docs on PR/push and uploads artifact..github/workflows/docs-deploy.ymlpublishessite/to GitHub Pages.scripts/test-docs-local.sh+ Make targets (docs-*).Why
How to Test
make lint(yamllint)make docs-buildthenmake docs-serve(http://127.0.0.1:8000)make docs-testmake clean build testCI/Secrets
QUAY_USERNAME,QUAY_PASSWORD,ANSIBLE_HUB_TOKENregistry.redhat.io:REDHAT_REGISTRY_USERNAME,REDHAT_REGISTRY_PASSWORDBackwards Compatibility
Screenshots/Links
site_urlset to repo Pages URL.Checklist
Podman-first Docs + CI Overhaul: EE Build, Docs Site, and Pages Deploy