Generating simple custom resource and deployment files

The prerequisites.py script is provided in the container-samples repository to help you prepare for the container installation. The script generates property files for the selected components in your deployment and must be run before your deployment is installed.

Before you begin

Before you use the prerequisites.py script to generate the property files, make sure that you review the following sections along with accompanied links:

The prerequisites.py script uses the following utility tools and needs them to be installed on your client machine.

  • Kubernetes CLI
  • Python
  • container-samples repository from GitHub
  • Java™
To install the specified tools that are used by the prerequisites.py script, see topic Preparing a client to connect to the cluster.

If the script finds that any of these tools are missing on the client, it reports which tools are missing and provides a choice to install the tool.

About this task

Instead of going through the many documented steps to create the databases and secrets for the components in your deployment, you can use the script to generate the SQL templates that assist in creating the databases and YAML files to utilize when creating the Kubernetes secrets.

The prerequisite scripts also generate a simple custom resource that includes all the essential elements that are necessary for a deployment. By default, it includes Content Pattern and deploys the Content Platform Engine, GraphQL, and Navigator components.

After you generate the custom resource, you can add additional configuration according to your specific requirements.

The prerequisites.py script has three modes.

gather

The gather mode helps gather information about your desired deployment. When you run the script in gather mode, it creates property files that you need to fill. The gather command comes with two options: new or move.

generate
The generate mode generates the DB SQL statement files, Kubernetes secrets YAML files, and the custom resource YAML template based on the gathered information from the property files.
validate
The validate mode checks whether the generated databases and secrets are correct and ready to use in a container deployment. It also validates the connections to external services and the usage of storage classes along with the option to continue with the process and create the deployment by applying the custom resource YAML file.

After you downloaded the container-samples repository, change the directory to the container-samples/scripts folder.

The script can be run from this location and has the following options:

python3 prerequisites.py --help

Usage: prerequisites.py [OPTIONS] COMMAND [ARGS]...

FileNet Content Manager Deployment Prerequisites CLI.

Options:
  --version                      Show version and exit. 
  --help                         Show this message and exit.

Customization and Utils:
  --silent     --no-silent       Enable Silent Install (no prompts). [default: no-silent]
  --verbose    --no-verbose      Enable verbose logging. [default: no-verbose]
  --dryrun     --no-dryrun       Perform a dry run [default: no-dryrun]

Commands:
  gather             Gather the prerequisites for FileNet Content Manager Deployment.
  generate           Generate the prerequisites for FileNet Content Manager Deployment.
  validate           Validate the prerequisites for FileNet Content Manager Deployment.
When you run the script in interactive mode, you can specify the mode that you want. When you run the script without specifying a mode, it runs in all modes. The following command runs the script interactively:
python3 prerequisites.py
Tip: Before you run the script in silent mode, make sure that you fill the ./scripts/silent_config/silent_install_prerequisites.toml file and then run the following command:
python3 prerequisites.py --silent

By default the prerequisites script logs all errors to the console and to a file named prerequisites.log, in your working directory.

To get all information in addition to the default, you can enable verbose mode.
python3 prerequisites.py --verbose generate

Procedure

  1. Open a terminal or command prompt and navigate to the directory where the container-samples repository was downloaded:
    cd ./container-samples/scripts
  2. Run the following command to install the necessary Python packages from the requirements.txt file:
    python3 -m pip install -r requirements.txt
  3. Run the script in the "gather" mode.
    • Gather mode (new):
      For a new deployment, running the gather command without any options requests all information. To run the gather command for a new deployment:
      1. Run the prerequisite script with the gather command.
        python3 prerequisites.py gather
      2. Follow the prompts and supply the required information.
    • Gather mode (silent)

      Gather mode can be run silently by providing all values in a configuration file. To run the gather command with the --silent flag:

      1. Fill out the ./scripts/silent_config/silent_install_prerequisites.toml.
      2. Use the comments in the file to help you enter values for the required parameters.
      3. Run the prerequisites script with the gather command and silent flag.
        python3 prerequisites.py gather --silent
    • Gather mode (move):
      If you are moving from traditional deployment to container environment, run the gather command with the move flag. Using this option extracts deployment information from the CPE configuration manager profile used for your traditional WebSphere® Application Server installation and prefills the property files. To run the gather command with the move flag:
      1. Copy the Configuration Manager files from your Content Platform Engine or Navigator Configuration Manager profile. The list of accepted files is as:
        • configurejdbcecm.xml​
        • configureldap.xml​
        • configurejdbcgcd.xml
        • configurejdbcos.xml
        You can supply the entire configuration manager profile folder with all of its contained files. Or you can supply of subset of only necessary files. If you do not want to include some of the information, remove the file from the folder. You can supply multiple ObjectStore or LDAP xml files, which can be denoted as, for example, configurejdbcos.2.xml.
      2. Place all files in a folder that is accessible to the prerequisites scripts.
      3. Run the prerequisites script with the gather command and move flag. Add the path of the folder that contains the XML file.
        python3 prerequisites.py gather --move <PathToFolder>
      4. After you enter all the required information, the propertyFile folder is created in your working directory. This folder contains folders for your SSL certificates (if SSL is enabled), and property files.
      Note: For security reasons, passwords are not extracted from the configuration manager files and always need to be reentered.
      Note: Triple quotations are used to preserve special characters for passwords, user names, and client secrets. Some characters need to be escaped, such as / by adding an extra /.
  4. Edit the property files and enter information where the value is <"Required">. If SSL is enabled, make sure that the SSL certificates are copied to the respective folders. If connecting to any external services over SSL, the required certificate can be placed in propertyFile/ssl-certs/trusted-certs.
    Note: All supplied SSL Certificates need to be in PEM format. The following is the list of accepted file extensions:
    • .crt
    • .cer
    • .pem
    • .cert
    • .key
    • .arm
    You need to complete the required information in all property files before you move to the generate mode.
  5. Run the prerequisites script with the generate command.
    python3 prerequisites.py generate 

    If any value is missing from the property file, the script exits and gives a summary of the elements that need to be filled out. Follow the supplied remediation steps to correctly fill out the property files.

    When the script is successful, you can find all the generated artifacts in the generatedFolder in your working directory. The generated artifacts include files that define:
    • Database SQL Templates
    • Kubernetes secrets with SSL certificates
    • Kubernetes secrets with sensitive configuration data
    • Custom Resource YAML (FNCMCluster)
    Note: You need to consider the generated database SQL templates as templates that need to be reviewed and modified to fit your environment before you apply them. For security reasons, all passwords are XOR encoded in all generated files. For additional parameters and advanced customizations, you can add them to the generated custom resource, before applying to your cluster or database services.
  6. Review and validate the generated files and artifacts.
    1. (Option 1)If your deployment is part of an online cluster, you can use the prerequisites script to validate your settings and apply the generated files to your cluster.
      You can validate the following for the OCP cluster:
      • whether storage classes exist.
      • whether PVCs can be created with the provided storage classes and are Read Write Many (RWX).
      • whether all supplied user and groups exist in configured LDAPs.
      • Database and LDAP server reachability.
      • Database and LDAP SSL cipher suite.
      • Database and LDAP connection over non-SSL or SSL.
      • Latency ranges for database and LDAP connections.
      Note: Validation for FIPS deployments, require FIPS enabled nodes to pass.
      Run the prerequisites script with the validate command.
      python3 prerequisites.py validate

      When all validation passes, the script can apply the files to the cluster. If validation fails, go back and edit your property files to fix the issue. If the issue is resolved, make sure that you regenerate your files and repeat step 5.

      To apply the generated artifacts manually, see Applying the custom resource.

    2. (Option 2)If the client was not set up manually, for example, if your deployment is part of an offline cluster:
    You can copy the entire prerequisites folder to the FileNet Content Manager stand-alone operator. Running the validation mode within the cluster, you can check connections for services that are accessible only inside the Kubernetes cluster. This method assumes that the operator is already deployed.
    1. Obtain the name of the FNCM stand-alone operator.
      export OPERATOR=$(kubectl get pods | grep operator | awk '{print $1}')
    2. Copy the prerequisites folder to the Operator pod.
      kubectl cp prerequisites/ $OPERATOR:/opt/ansible
    3. Start a terminal inside the Operator pod.
      kubectl exec -it $OPERATOR -- bash
    4. Navigate to the working directory.
      cd /opt/ansible/prerequisites
    5. Run the validate command.
      python3 prerequisites.py validate

      When all validation passes, you can choose to apply all the generated artifacts to the cluster. If validation fails, go back and edit your property files to fix the issue. If the issue is resolved, be sure to regenerate your files and repeat step 5.

      To apply the generated artifacts manually, see Applying the custom resource.

      Note: Files within the operator do not persist. If you change the property files within the FileNet Content Manager stand-alone operator, make sure that you copy them out to keep a backup.

What to do next

After all validation passes, and once you generate the deployment artifacts, you can do one of the following: