Deployment architecture

Deployment architecture overview

HeartAI provides supportive environments to assist developers and contributors. A readily deployable developer environment is managed through Docker Compose, allowing transportable and reproducible development system deployments. Unit and integration testing frameworks are provided by ScalaTest and Akka Testing. Source contributions are managed through Git and GitHub source control management software. The HeartAI GitHub repository is integrated with GitHub Actions, providing mechanisms to test, package, and deploy source software to the HeartAI production environment. System resources are deployed to the HeartAI OpenShift cluster through integration with the OpenShift GitOps Operator. A core component of this process is the management of cluster resources with Argo CD. These approaches allow the validation and deployment of resources to occur through the GitHub managed review and deployment processes, and provide a supportive framework to encourage developer and contributor productivity and experience.

GitHub implementation

HeartAI source code, task and project management, and associated processes are administered through the Git version control software and the GitHub software development framework. Git and GitHub are the primary mechanisms to contribute to, manage, and deploy HeartAI. These frameworks provide structured and dynamic processes for administrators and developers to manage HeartAI, including support for:

  • Software, document, and process version control.
  • Project and product management tooling.
  • Functionalities to package and deploy software for both local machine and production environments.
  • Administrator and developer GitHub account management.
  • Utilities for software testing, analysis, and deployment.
GitHub implementation

HeartAI source code, task and project management, and associated processes are administered through the Git version control software and the GitHub software development framework. Further information about the HeartAI implementation of GitHub may be found with following documentation:

HeartAI repository branches allow different aspects of the repository to be separated and developed independently. The following branches implement the primary functionality of HeartAI and are protected by default:

Branch name Description Restrictions Requirements
master Representative branch for HeartAI system deployment Must be merged into from a pull request. Pull request must have at least one administrator review
gh-pages Representative branch for HeartAI website deployment Must be merged into from a pull request. Pull request must have at least one administrator review

To apply source contribution to these branches, contributors must pull request their branch to merge with a corresponding origin branch, typically the protected branches noted above. Contributions to these branches are governed by an administrative review process as represented with the following figure:

review-process-for-source-contribution.svg

With administrative approval, the contributor’s branch may be merged with the nominated origin branch, and will become part of the representative branches of the HeartAI source. The representative branches, master and gh-pages, trigger downstream deployment behaviour following modification to the origin source. This includes unit and integration testing, publication of representative packages and images, and deployment to HeartAI instances of Red Hat OpenShift.

GitHub Actions process

The HeartAI GitHub repository is integrated with GitHub Actions, providing mechanisms to test and package source software. These actions are typically triggered following commits to origin, with action functionality corresponding to the nature and location of the commit. The following table provides a general overview of GitHub Actions functionality within the HeartAI source repository:

GitHub Action job Function Event trigger
Core service testing Perform integration testing of the service Push to origin/*
Hello world service testing Perform integration testing of the service Push to origin/*
Hello world service publish Build and publish service to Quay image repository Push to origin/master
HIB interface service testing Perform integration testing of the service Push to origin/*
HIB interface service publish Build and publish service to Quay image repository Push to origin/master
HIB FHIR translation service testing Perform integration testing of the service Push to origin/*
RAPIDx AI service testing Perform integration testing of the service Push to origin/*
RAPIDx AI service publish Build and publish service to Quay image repository Push to origin/master
  • Performing integration testing of the service:
name: "Hello world service testing"
on:
  push:
jobs:
  hello-world-service-test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:latest
        env:
          TZ: Australia/Adelaide
          POSTGRES_DB: heartai
          POSTGRES_USER: heartai
          POSTGRES_PASSWORD: heartai
          POSTGRES_ROOT_PASSWORD: heartai_root
        ports:
          - "5432:5432"
        options: >-
          --name heartai-postgres
          --hostname heartai-postgres
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      keycloak:
        image: quay.io/keycloak/keycloak:16.1.1
        env:
          TZ: Australia/Adelaide
          DB_VENDOR: h2
          KEYCLOAK_USER: heartai
          KEYCLOAK_PASSWORD: heartai
        ports:
          - "9990:8080"
        options: >-
          --name heartai-keycloak
          --hostname heartai-keycloak
    steps:
      - name: "Initialise environment"
        run: sudo chown -R $USER:$USER /home/runner/work/HeartAI
      - name: "Wait for services readiness"
        uses: nev7n/[email protected]
        with:
          url: 'http://localhost:9990/'
          responseCode: 200
          timeout: 60000
          interval: 1000
      - name: "Checkout HeartAI repository"
        uses: actions/[email protected]
      - name: "Setup Keycloak realm"
        run: source $GITHUB_WORKSPACE/deploy/development/keycloak/shell/createDevRealm.sh
      - name: "Setup Scala environment"
        uses: olafurpg/[email protected]
        with:
          java-version: "[email protected]"
      - name: "Use SBT to compile and test Scala"
        run: "sbt -v -Dfile.encoding=UTF-8 helloWorldIMPL/test"
  • Building and publishing the service:
name: "Hello world service publish"
on:
  push:
    branches:
      - master
jobs:
  hello-world-service-publish:
    runs-on: ubuntu-latest
    steps:
      - name: "Login to Quay"
        uses: docker/[email protected]
        with:
          registry: quay.io/heartai
          username: ${{ secrets.QUAY_USERNAME }}
          password: ${{ secrets.QUAY_PASSWORD }}
      - name: "Checkout"
        uses: actions/[email protected]
      - name: "Setup Scala"
        uses: olafurpg/[email protected]
        with:
          java-version: "[email protected]"
      - name: "Publish"
        run: "sbt -Ddocker.registry=quay.io/heartai helloWorldIMPL/docker:publish"

GitHub UI for repository overview

The following example shows the GitHub web interface for the repository overview. This page provides a high-level overview of the repository, and includes information such as:

  • The repository file structure, with detail about the most recent commit for the directory / file.
  • The rendered GitHub README documentation.
  • Repository metadata, including corresponding website(s) and most recent software version release.
  • Published repository packages.
  • Repository contributors.

Example: GitHub UI for repository overview

github-1-home.png

GitHub UI for commits

The following example shows the GitHub web interface for a Git commit, representing an incremental change to the repository history. For commits, GitHub provides functionalities such as:

  • Assignment of the commit with a repository Git commit ID as a unique SHA-1 hash of commit information.
  • What changes were made to the repository.
  • Who authored the changes.
  • Functionality and metrics to understand the extent of the changes.

Example: GitHub UI for repository commit

github-8-commit.png

GitHub UI for pull requests

The following examples show the GitHub web interface for a GitHub pull request, representing a request to merge one repository branch with another. For pull requests, GitHub provides functionalities such as:

  • Request process to submit an incremental update to a primary repository branch.
  • Ability to assign reviewers to review a pull request.
  • Ability to label pull requests, and associate pull requests to GitHub projects and GitHub milestones.
  • Enforcement of repository policies, such as requiring at least one administrator review and approval before accepting a pull request.
  • Integrated testing and event-driven behaviour through GitHub Actions capabilities.

Example: GitHub UI for repository closed pull requests

github-4b-pull-requests.png

Example: GitHub UI for repository pull request

github-4-pull-request.png

GitHub UI for networks

The following example shows the GitHub web interface for GitHub networks. This graph allows an interactive visualisation of repository development history. The GitHub web interface for networks provides:

  • A scrollable and interactive visualisation of repository development history.
  • Linking of network data points corresponding to a repository Git commit ID.
  • Popup information when interacting with network data points, displaying further information about the corresponding commit.

Example: GitHub UI for repository network

github-7-network.png

GitHub UI for issues

The following examples show the GitHub web interface for GitHub issues. This page provides functionalities to support project planning, task management, and team management. An issue typically represents a well-defined task or query in relation to the repository, and the issues web interface provides a centralised framework to manage these tasks. For issues, GitHub provides support for:

  • Issue creation with authorship corresponding to the GitHub user account.
  • Functionalities for labeling and tagging issues.
  • Assigning repository members to the issue.
  • Assigning issues to GitHub projects.
  • Assigning issues to GitHub milestones.

Example: GitHub UI for repository open issues

github-2-issues.png

Example: GitHub UI for repository closed issues

github-2b-issues.png

GitHub UI for milestones

The following example shows the GitHub web interface for GitHub milestones. This page provides functionalities to support project planning over larger time epochs. A milestone typically bundles repository issues related to a major platform or project development goal. For milestones, GitHub provides support for:

  • Documenting milestone purposes and goals.
  • Linkage between repository issues and a milestone.
  • Providing an overview of milestone development progress.

Example: GitHub UI for repository milestone open issues

heartai-software-github-milestones

GitHub UI for projects

The following example shows the GitHub web interface for GitHub projects, providing Kanban-like functionalities to manage projects and product. For projects, GitHub provides functionalities such as:

  • Project tasks that are linkable to corresponding repository issues, with inheritance of issue features such as web interface interactivity integrations.
  • Inheritance of GitHub issue assignees and labels.
  • Customisable board columns.

Example: GitHub UI for repository project board

github-3-projects.png

GitHub UI for releases

The following example shows the GitHub web interface for GitHub releases. This feature provides functionalities for tagging, packaging, and delivering repository software. Releases are typically created in relation to a major repository milestone. GitHub releases support:

  • Linking of the release at a point in time of the repository history corresponding to a repository Git commit ID.
  • Tagging the release. GitHub provides additional support for tags that are structured as software versions.
  • The repository source and software may be bundled and downloaded through the release page. Typical bundles are composed as zip and tar.gz files.
  • The release version is displayed on the web interface repository overview.

Example: GitHub UI for repository release

github-5-release.png

GitHub UI for GitHub Actions

The following example shows the GitHub web interface for GitHub Actions. This feature allows general event-driven behaviour to occur following interaction with GitHub as a Git commit, such as behaviour driven by a Git push to the GitHub repository, or as part of a GitHub pull request process. These capabilities are backed by Microsoft Azure cloud resources, and include broad access to compute services. This is particularly suitable for performing unit- and integration-testing of repository software and for deployment processing generally. The GitHub Actions web interface provides:

  • An overview of all GitHub Actions workflows and jobs that have been registered with the repository.
  • Linking of the GitHub Actions workflow with a repository Git commit ID.
  • The ability to view the GitHub Actions workflow in real-time, including logging functionality through backing Microsoft Azure cloud resources.

Example: GitHub UI for repository GitHub Actions workflow

github-actions.png

GitOps deployment process

Within HeartAI OpenShift instances, the OpenShift GitOps Operator provides declarative approaches for GitOps lifecycle management and continuous delivery. A core component of this process is the management of cluster resources with an integrated Argo CD instance. The Argo CD framework defines a Kubernetes Application custom resource that provides functionality to synchronise with GitHub hosted source repositories. Through these Application resources, Argo CD monitors for updates to the HeartAI GitHub repository, and synchronisation is triggered when modifications are made to the master branch. Triggered behaviour includes applying the cluster resource declaration files to the HeartAI OpenShift instance, which coordinates the deployment of OpenShift resources to the cluster environment. These approaches allow the deployment of platform resources to occur through the GitHub managed review and deployment processes, and provide a supportive framework to optimise developer and contributor productivity and experience.

Red Hat OpenShift implementation

HeartAI orchestrates system services with the Kubernetes-based Red Hat OpenShift container platform. Further information about the HeartAI implementation of Red Hat OpenShift may be found with the following documentation:

Argo CD implementation

Within HeartAI OpenShift instances, Argo CD provides declarative approaches for GitOps lifecycle management and continuous delivery. Further information about the HeartAI Argo CD implementation may be found with the following documentation:

Example: Argo CD OpenShift declaration

The following OpenShift declaration shows the Argo CD Application resource for the HeartAI HelloWorldService production environment. Within the corresponding directory path at src/services/hello_world/hello_world_IMPL/deploy/prod/ there are a collection of OpenShift declaration files for specifying the HelloWorldService deployment to OpenShift. Argo CD synchronises the declared state of this directory with that of the OpenShift cluster, and applies any relevant operations to ensure the alignment of these states.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: heartai-hello-world-prod
  namespace: openshift-gitops
spec:
  destination:
    namespace: heartai-hello-world-prod
    server: "https://kubernetes.default.svc"
  project: default
  source:
    directory:
      recurse: true
    path: "src/services/hello_world/hello_world/hello_world_IMPL/deploy/prod/yaml/"
    repoURL: "https://github.com/Lukah0173/HeartAI.git"
    targetRevision: "master"
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Example: Argo CD GitOps process

The following diagram describes the process of Argo CD monitoring the corresponding GitHub repository for state changes to the master branch, and applying any changes to state to the corresponding OpenShift environment:

heartai-argocd-gitops-process.svg

Example: Argo CD user interface

The following images show the Argo CD user interface:

Argo CD UI applications overview

The following image shows the Argo CD web interface for Application resources. The Application web interface provides:

  • An overview of Application resources that are managed by Argo CD.
  • Information about Application resources, including:
    • The associated project that manages the Application resource.
    • Labels that have been applied to the Application.
    • Health and synchronisation status.
    • The corresponding GitHub repository path.
    • The target branch of the repository.
    • The Application deployment destination.
    • The associated Application namespace.

heartai-argocd-applications-tiles.png

Argo CD UI applications overview with rows view

The following example shows the Argo CD web interface for Argo CD Application resources with a rows view. The Application web interface provides:

  • An overview of Application resources that are managed by Argo CD.
  • Information about Application resources, including:
  • The associated project that manages the Application resource.
  • Labels that have been applied to the Application.
  • Health and synchronisation status.
  • The corresponding GitHub repository path.
  • The target branch of the repository.
  • The Application deployment destination.
  • The associated Application namespace.

heartai-argocd-applications-rows.png

Argo CD UI application resources tree

The following image shows the Argo CD web interface for the resources of the heartai-acs Application with a tree view. This representation displays the management association between these resources. The Application tree view provides:

  • Information about the Application, including:
    • The health of the Application.
    • Details about current and previous synchronisation states.
  • An overview of the resources that are managed by the Application.
  • The hierarchical management structure between these resources.
  • Information about Application resources, including:
    • The resource name and icon.
    • Resource-level health and synchronisation status.

heartai-argocd-application-tree.png

Argo CD UI application resources list

The following example shows the Argo CD user interface for the Argo CD Application resources of the heartai-acs namespace with a list view. This displays application resources for the HeartAI Red Hat Advanced Cluster Security production environment.

heartai-argocd-application-list.png

Argo CD UI application pods

The following example shows the Argo CD user interface for the application pods of the heartai-acs namespace. This displays application pod resource deployments for the HeartAI Red Hat Advanced Cluster Security production environment.

heartai-argocd-application-pods.png

Argo CD UI application networking

The following example shows the Argo CD user interface for the application networking of the heartai-acs namespace. This displays application networking for the HeartAI Red Hat Advanced Cluster Security production environment.

heartai-argocd-application-network.png