Understanding the ibm-content-cortex-containers repository

Repository overview

The ibm-content-cortex-containers repository is organized into the following structure:

ibm-content-cortex-containers/

├── content-cortex
│ ├── ai-services
│ │ └── rbac
│ ├── content
│ │ └── rbac
│ ├── op-olm
│ └── turbonomics
├── license-service
│ ├── op-olm
│ └── rbac
└── usage-metering
├── ccx-metrics
│ ├── op-olm
│ └── rbac
├── scripts/
├── README.md
└── version.toml

Repository contents

Each directory in the repository serves a specific purpose in the deployment process:

descriptors/

Contains YAML descriptor files and custom resource templates for deploying Content Cortex components . The descriptors are organized by component type and include configuration templates for Content Cortex services, operator deployment, and supporting services. These descriptors serve as templates that you can customize for your specific deployment requirements. All installation files for Yaml or OLM based install exist as a reference in this folder. All OLM based deployment files can be found in the respectice op-olm folder, and all role based access control (RBAC) can be found in rbac folders.

scripts/

The scripts directory contains a comprehensive set of Python scripts that are designed to streamline deployment, management, and troubleshooting of Content Cortex systems in containerized environments. All scripts support the following features:

• Help mode - Provides information about the script and its usage
• Silent mode - Runs the script without prompts by using configuration files from the scripts/silent_config directory
• Verbose mode - Provides detailed information about script execution by using the --verbose flag
• Dry-run mode - Use the --dryrun flag to simulate script execution without making changes
• Automatic backups - Creates backups of existing output files in scripts/backups when rerunning scripts

The suite includes the following scripts:

load_images.py

Loads container images into your private image registry. This script is essential for offline deployments and air-gapped Red Hat® OpenShift® Container Platform environments where direct access to the IBM Entitled Registry is not available. The script operates in three modes:

• Generate mode - This mode creates a list of images to be loaded and the generated file is saved in the scripts/imageDetails directory and can be adjusted to include only required images.
• Push mode - This mode loads the generated file and pushes images to your private registry.
• All mode - This mode combines generate and push modes.

prerequisites.py

Automates the deployment preparation phase by gathering information, generating configuration files, and validating system prerequisites. This script operates in three modes:

• Gather mode - Collects information about your desired deployment configuration. Use the mode to interactively gather deployment details. Include the --move flag when you run the script for a migration from a traditional deployment to a containerized environment.
• Generate mode - Creates SQL templates and YAML files based on gathered information. Use the mode to produce deployment artifacts.
• Validate mode - Verifies connections to external services (databases, LDAP, IDP, SCIM) and validates storage class usage. Use the mode to check all connections. You can skip specific validations using flags like --skip-database, --skip-ldap, --skip-idp, --skip-scim, or --skip-storageclass. Include the --apply flag to automatically apply generated artifacts to the cluster.

Note: All passwords, usernames, and client secrets are triple-quoted to preserve special characters. Backslash characters (\) must be escaped with an additional backslash (\\).

deploy_operator.py

Automates the deployment of the Content Cortex operator using Helm charts. This script handles namespace creation, operator installation, helm chart download, and initial setup. The script supports both Red Hat OpenShift Container Platform and CNCF Kubernetes deployments. It provides both interactive and silent modes for operator deployment, making it suitable for both manual and automated deployments across different Kubernetes platforms and deployment methods. This script will detect the current state of the deployment and provide options for fresh install, upgrade and migration to Helm.

upgrade_deployment.py

Manages the upgrade process for existing Content Cortex deployments. Upgrades the deployed custom resource with options to scale down and apply the updated configuration. Run with --dryrun to simulate the upgrade without making changes.

The script automates the upgrade workflow, including version compatibility checks and rolling updates of components, helping ensure a smooth transition to newer versions while minimizing downtime.

Important: This script does not perform database or storage backups. You must back up your databases and persistent storage separately before running an upgrade. Use the must_gather.py script to back up the custom resource configuration.

clean_deployment.py

Removes and cleans up deployment resources from your cluster. This script operates in three modes:

• Operator mode - Cleans up only the Content Cortex operators.
• Deployment mode - Cleans up the deployed custom resource. Run with --dryrun to simulate the cleanup without making changes.
• All mode - Cleans up both the operator and the deployed custom resource.

The script removes custom resources, secrets, configmaps, and other Kubernetes objects. It is useful for resetting your environment, troubleshooting deployment issues, or preparing for a fresh installation.

Important: This script does not remove persistent volume claims (PVCs). You must manually delete PVCs if you want to remove persistent storage.

must_gather.py

Collects comprehensive diagnostic information and logs from your Content Cortex deployments for troubleshooting purposes. The script gathers pod logs, configuration details, resource status, deployment artifacts, operator logs, custom resource (CR) backups, and other relevant data that can be shared with IBM Support for problem analysis. After completion, the collected data is packaged in scripts/MustGather.tar.gz. This script is particularly useful for backing up custom resource configurations before performing upgrades or major changes.

requirements.txt

Contains the list of required Python packages and their dependencies needed to run the scripts. This file ensures that all necessary Python libraries are available for script execution, including packages for Kubernetes API interaction, YAML processing, database connectivity, and other essential functionality.

silent_config/

Contains configuration files for running scripts in silent mode without interactive prompts. Each script that supports silent mode has a corresponding configuration file in this directory where you can pre-define all required parameters. To use silent mode, fill out the appropriate configuration file with your deployment details and run the script with the --silent flag. This approach is ideal for automated deployments, CI/CD pipelines, and scenarios where consistent, repeatable deployments are required without manual intervention.

CHANGELOG.md

Documents the version history and changes made to the scripts. This file provides a chronological record of new features, enhancements, bug fixes, and breaking changes for each script version. Each release entry includes the version number, release date, and categorized changes (features, fixes, and breaking changes). Review this file to understand what has changed between versions, identify new capabilities such as automatic version detection, enhanced validation checks, improved error handling, and plan for any required updates to your deployment processes when upgrading to a newer version of the scripts. The changelog helps you track improvements like support for digest-based image loading, enhanced certificate validation, namespace-scoped operations, and other operational enhancements.

For the complete list of available scripts, detailed usage instructions, and the latest updates, see Scripts directory on GitHub .

README.md

Provides an overview of the repository, including version information, prerequisites, and links to documentation. This file serves as the starting point for understanding the repository contents and usage.

version.toml

Contains version metadata for the repository to help ensure compatibility between the repository contents and your deployment environment. The above scripts will use this file to determine correct install version and Helm chart download. The file includes the following key information:

• Release date and full release name.
• Repository version and application version.
• Helm chart version for Helm-based deployments.

Always verify that the version information in this file matches your target deployment version before proceeding with installation or upgrade operations.

Using the repository

After downloading the repository, you can:

• Navigate to the descriptors/ directory to find and customize deployment templates for your environment
• Use scripts from the scripts/ directory to automate deployment tasks and administrative operations
• Reference the README.md file for version-specific guidance and important notes
• Verify version compatibility using the version.toml file before proceeding with deployment

Version-specific repositories

The ibm-content-cortex-containers GitHub repository maintains different branches and releases for each product version. Always download the repository version that corresponds to your target Content Cortex Content Manager version to ensure compatibility and access to the correct deployment artifacts.