Validated Patterns

Deploying the Medical Diagnosis pattern

Prerequisites
  • An OpenShift cluster

    • To create an OpenShift cluster, go to the Red Hat Hybrid Cloud console.

    • Select OpenShift -> Red Hat OpenShift Container Platform -> Create cluster.

    • The cluster must have a dynamic StorageClass to provision PersistentVolumes. Verify that a dynamic StorageClass exists before creating one by running the following command:

      $ oc get storageclass -o custom-columns=NAME:.metadata.name,PROVISIONER:.provisioner,DEFAULT:.metadata.annotations."storageclass\.kubernetes\.io/is-default-class"
      Example output
      NAME      PROVISIONER       DEFAULT
      gp2-csi   ebs.csi.aws.com   <none>
      gp3-csi   ebs.csi.aws.com   true

      For more information about creating a dynamic StorageClass, see the Dynamic provisioning.

  • A GitHub account and a token for it with repositories permissions, to read from and write to your forks.

  • An S3-capable storage set up in your public or private cloud for the x-ray images

  • The Helm binary, see Installing Helm For installation tooling dependencies, see Patterns quick start.

The Medical Diagnosis pattern does not have a dedicated hub or edge cluster.

Setting up an S3 Bucket for the xray-images

An S3 bucket is required for image processing. The utilities repo and specifically the aws-tools directory contains some S3 tools and EC2 tools.

For the official documentation on creating the buckets on AWS and other cloud providers, see the following links:

Utilities

Follow this procedure to use the scripts provided in the utilities repo to configure and S3 bucket in your AWS environment for the x-ray images.

Procedure
  1. Fork the utilities repository on GitHub. Forking the repository allows you to update the repository as part of the GitOps and DevOps processes.

  2. Clone the forked copy of this repository.

    $ git clone git@github.com:validatedpatterns/utilities.git
  3. Go to your repository: Ensure you are in the root directory of your Git repository by using:

    $ cd utilities
  4. Run the following command to set the upstream repository:

    git remote add -f upstream git@github.com:validatedpatterns/utilities.git
  5. Change to the aws-tools directory:

    $ cd aws-tools
  6. Run the following commands in your terminal to export environment variables for AWS authentication:

    export AWS_ACCESS_KEY_ID=AKXXXXXXXXXXXXX
    export AWS_SECRET_ACCESS_KEY=gkXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    Ensure that you replace values with your keys

  7. Create the S3 bucket by running the following command:

    $ python s3-create.py -b kevtest-bucket -r us-east-1 -p
  8. Copy over the data from the validated patterns public bucket to the created bucket for your demo.

    $ python s3-sync-buckets.py -s validated-patterns-md-xray -t kevtest-bucket -r us-east-1

Note the name of the bucket for further pattern configuration. Later you will update the bucketSource in the values-global.yaml file, where there is a section for s3:.

Preparing for deployment

Procedure
  1. Fork the medical-diagnosis repository on GitHub. You must fork the repository because your fork will be updated as part of the GitOps and DevOps processes.

  2. Clone the forked copy of this repository.

    $ git clone git@github.com:<your-username>/medical-diagnosis.git
  3. Go to your repository: Ensure you are in the root directory of your Git repository by using:

    $ cd /path/to/your/repository
  4. Run the following command to set the upstream repository:

    $ git remote add -f upstream git@github.com:validatedpatterns/medical-diagnosis.git
  5. Verify the setup of your remote repositories by running the following command:

    $ git remote -v
    Example output
    origin	git@github.com:kquinn/medical-diagnosis.git (fetch)
    origin	git@github.com:kquinn/medical-diagnosis.git (push)
    upstream	git@github.com:validatedpatterns/medical-diagnosis.git (fetch)
    upstream	git@github.com:validatedpatterns/medical-diagnosis.git (push)
  6. Create a local copy of the Helm values file that can safely include credentials.

    Do not commit this file. You do not want to push personal credentials to GitHub.

    Run the following commands:

    $ cp values-secret.yaml.template ~/values-secret-medical-diagnosis.yaml
    Example values-secret.yaml file
    version "2.0"
    secrets:
      # NEVER COMMIT THESE VALUES TO GIT
    
      # Database login credentials and configuration
      - name: xraylab
        fields:
        - name: database-user
          value: xraylab
        - name: database-host
          value: xraylabdb
        - name: database-db
          value: xraylabdb
        - name: database-master-user
          value: xraylab
        - name: database-password
          onMissingValue: generate
          vaultPolicy: validatedPatternDefaultPolicy
        - name: database-root-password
          onMissingValue: generate
          vaultPolicy: validatedPatternDefaultPolicy
        - name: database-master-password
          onMissingValue: generate
          vaultPolicy: validatedPatternDefaultPolicy
    
      # Grafana Dashboard admin user/password
      - name: grafana
        fields:
          - name: GF_SECURITY_ADMIN_USER:
            value: root
          - name: GF_SECURITY_ADMIN_PASSWORD:
            onMissingValue: generate
            vaultPolicy: validatedPatternDefaultPolicy

    By default, the Vault password policy generates the passwords for you. However, you can create your own passwords.

  7. If you want to create custom passwords for the database users you will need to edit this file:

    $ vi ~/values-secret-medical-diagnosis.yaml

    When defining a custom password for the database users, avoid using the $ special character as it gets interpreted by the shell and will ultimately set the incorrect desired password.

  8. Create and switch to a new branch named my-branch, by running the following command:

    $ git checkout -b my-branch
  9. Edit the values-global.yaml updating the S3 and datacenter details.

    $ vi values-global.yaml
    Example edited values-global.yaml file
    global:
      pattern: xray
    
      options:
        useCSV: False
        syncPolicy: Automatic
        installPlanApproval: Automatic
    
      datacenter:
        storageClassName: gp3-csi
        cloudProvider: aws
        region: us-east-1
        clustername: mytestcluster
        domain: aws.validatedpatterns.io
    
      xraylab:
        namespace: "xraylab-1"
    
        s3:
          # Values for S3 bucket access
          # bucketSource: "provide s3 bucket name where images are stored"
          bucketSource: kevtest-bucket
          # Bucket base name used for image-generator and image-server applications.
          bucketBaseName: "xray-source"
    
    main:
      clusterGroupName: hub
      multiSourceConfig:
        enabled: true
        clusterGroupChartVersion: 0.9.*
    
    # Example Configuration
      #datacenter:
      #  cloudProvider: aws
      #  storageClassName: gp2
      #  region: us-east-1
      #  clustername: example-sample
      #  domain: patterns.redhat.com
  10. Add values-global.yaml to the staging area:

    $ git add values-global.yaml
  11. Commit the staged changes with a message:

    $ git commit -m "Update values-global.yaml"
  12. Push the changes to your forked repository:

    $ git push origin my-branch

You can proceed to install the Medical Diagnosis pattern pattern by using the web console or from command line by using the script ./pattern.sh script.

To install the Medical Diagnosis pattern pattern by using the web console you must first install the Validated Patterns Operator. The Validated Patterns Operator installs and manages Validated Patterns.

Installing the Validated Patterns Operator using the web console

Prerequisites
  • Access to an OpenShift Container Platform cluster by using an account with cluster-admin permissions.

Procedure
  1. Navigate in the Red Hat Hybrid Cloud Console to the OperatorsOperatorHub page.

  2. Scroll or type a keyword into the Filter by keyword box to find the Operator you want. For example, type validated patterns to find the Validated Patterns Operator.

  3. Select the Operator to display additional information.

    Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.

  4. Read the information about the Operator and click Install.

  5. On the Install Operator page:

    1. Select an Update channel (if more than one is available).

    2. Select a Version (if more than one is available).

    3. Select an Installation mode:

      The only supported mode for this Operator is All namespaces on the cluster (default). This installs the Operator in the default openshift-operators namespace to watch and be made available to all namespaces in the cluster. This option is not always available.

    4. Select Automatic or Manual approval strategy.

  6. Click Install to make the Operator available to the selected namespaces on this OpenShift Container Platform cluster.

Verification

To confirm that the installation is successful:

  1. Navigate to the OperatorsInstalled Operators page.

  2. Check that the Operator is installed in the selected namespace and its status is Succeeded.

Creating the Medical Diagnosis GitOps instance

Prerequisites

The Medical Diagnosis pattern is successfully installed in the relevant namespace.

Procedure
  1. Navigate to the OperatorsInstalled Operators page.

  2. Click the installed Validated Patterns Operator.

  3. Under the Details tab, in the Provided APIs section, in the Pattern box, click Create instance that displays the Create Pattern page.

  4. On the Create Pattern page, select Form view and enter information in the following fields:

    • Name - A name for the pattern deployment that is used in the projects that you created.

    • Labels - Apply any other labels you might need for deploying this pattern.

    • Cluster Group Name - Select a cluster group name to identify the type of cluster where this pattern is being deployed. For example, if you are deploying the Industrial Edge pattern, the cluster group name is datacenter. If you are deploying the Multicloud GitOps pattern, the cluster group name is hub.

      To know the cluster group name for the patterns that you want to deploy, check the relevant pattern-specific requirements.

  5. Expand the Git Config section to reveal the options and enter the required information.

  6. Leave In Cluster Git Server unchanged.

    1. Change the Target Repo URL to your forked repository URL. For example, change https://github.com/validatedpatterns/<pattern_name> to https://github.com/<your-git-username>/<pattern-name>

    2. Optional: You might need to change the Target Revision field. The default value is HEAD. However, you can also provide a value for a branch, tag, or commit that you want to deploy. For example, v2.1, main, or a branch that you created, my-branch.

  7. Click Create.

    A pop-up error with the message "Oh no! Something went wrong." might appear during the process. This error can be safely disregarded as it does not impact the installation of the Multicloud GitOps pattern. Use the Hub ArgoCD UI, accessible through the nines menu, to check the status of ArgoCD instances, which will display states such as progressing, healthy, and so on, for each managed application. The Cluster ArgoCD provides detailed status on each application, as defined in the clustergroup values file.

The Red Hat OpenShift GitOps Operator displays in list of Installed Operators. The Red Hat OpenShift GitOps Operator installs the remaining assets and artifacts for this pattern. To view the installation of these assets and artifacts, such as Red Hat Advanced Cluster Management (RHACM), ensure that you switch to Project:All Projects.

Wait some time for everything to deploy. You can track the progress through the Hub ArgoCD UI from the nines menu. The xraylab-database project appears stuck in a Degraded state. This is the expected behavior when installing using the OpenShift Container Platform console.

  • To resolve this you need to run the following to load the secrets into the vault:

    $ ./pattern.sh make load-secrets

    You must have created a local copy of the secret values file by running the following command:

    $ cp values-secret.yaml.template ~/values-secret-medical-diagnosis.yaml

The deployment will not take long but it should deploy successfully.

Alternatively you can deploy the Medical Diagnosis pattern pattern by using the command line script pattern.sh.

Deploying the cluster by using the pattern.sh file

To deploy the cluster by using the pattern.sh file, complete the following steps:

  1. Log in to your cluster by running the following command:

    $ oc login

    Optional: Set the KUBECONFIG variable for the kubeconfig file path:

    $ export KUBECONFIG=~/<path_to_kubeconfig>
  2. Deploy the pattern to your cluster. Run the following command:

    $ ./pattern.sh make install
  3. Verify that the Operators have been installed.

    1. To verify, in the OpenShift Container Platform web console, navigate to Operators → Installed Operators page.

    2. Check that the Red Hat OpenShift GitOps Operator is installed in the openshift-operators namespace and its status is Succeeded.

  4. Wait some time for everything to deploy. You can track the progress through the Hub ArgoCD UI from the nines menu.

    medical diags overview

As part of installing by using the script pattern.sh pattern, HashiCorp Vault is installed. Running ./pattern.sh make install also calls the load-secrets makefile target. This load-secrets target looks for a YAML file describing the secrets to be loaded into vault and in case it cannot find one it will use the values-secret.yaml.template file in the git repository to try to generate random secrets.

For more information, see section on Vault.

Verification

To check the various applications that are being deployed, you can view the progress of the OpenShift GitOps Operator.

Examine the medical-diagnosis-hub ArgoCD instance. You can track all the applications for the pattern in this instance.

  1. Check that all applications are synchronized. There are thirteen different ArgoCD applications that are deployed as part of this pattern.