ACD Custom Resource

The Acd resource is a Custom Resource Definition used to deploy and manage an instance of Annotator for Clinical Data service.

Just as other Kubernetes objects do, the Acd custom resource includes two nested object fields that govern the object’s configuration: the object Spec (desired state) and the object Status (current state). When a custom resource is created or updated, the desired state (Spec field) is updated and available immediately. Over time, the system will work to bring the Status into line with the Spec. These fields provide a standard way to report the state of the custom resource or ACD service instance.

For more information on the object spec, status, and metadata, see the Kubernetes API Conventions.

Spec
Status

Spec

Properties

Property	Description	Required	Default
Annotators	Which annotators are deployed for the instance	Yes	See doc below
Configuration Storage	Persistent volume requests	Yes	See doc below
License	License acceptance and usage	Yes	None
Network Policy	Network security policies	Yes	Enabled
Replicas	Number of replica nodes in the cluster	Yes	3
Resources	Resource specifications for instance	No	See doc below
Tenant Header	Unique header for multi-tenancy	No	None
Version	Annotator for Clinical Data Container Edition version	Yes	None

Annotators
Configuration Storage
License
Network Policy
Replicas
Resources
Tenant Header
Version

`Annotators`

Description

The Annotators property tells the deployment which annotator pods should be created as part of the deployment. At least one annotator needs to be enabled and by default all annotators are enabled.

Advanced Care Insights : discovers contextual information for problems, procedures, and medications identified in unstructured text
Attribute Detection : discovers domain specific attributes and associated values to be discovered in unstructured clinical text
Concept Detection : discovers matching terms from concept dictionaries
Concept Disambiguation : ranks term revelency based on sentence and document level information
Concept Value Detection : used with concept detection to discover values for matched dictionary concepts
Hypothetical Detection : discovers spans of text that are the object of a hypothetical statement
Model Broker: discovers key clinical concepts, such as medications, diagnoses, and procedures, with contextual scores.
Negation Detection : discovers the spans of text that are the object of a negation and also identifies the text that triggered the negation
Ontology : allows user to manage custom ontologies / dictionaries
Spell Checker : discovers misspelled words and phrases in a document and suggests corrections

Example

  Annotators:
    Advanced Care Insights:
      Enabled:  true
    Attribute Detection:
      Enabled:  true
    Concept Detection:
      Enabled:  true
    Concept Disambiguation:
      Enabled:  true

`Configuration Storage`

Description

The Configuration Storage property tells the deployment whether persistent storage is enabled and the type of storage being used. There are two required fields to configuration storage.

Storage : either File or S3 compatible storage.
File Storage : whether persistent storage is enabled, default is true.

If persistent is enabled the following additional properties are available:

PVC

PVC storage size : default 10 Gigabytes
Supplemental Group ID : only needs to be set if root(0) is not being used
Existing PVC name | name of the persistent volume claim
Storage Class Name : some storage options require specific storage class names

If S3 compatible (COS) is enabled these additional properties need to be set:

S3 Storage

Endpoint URL : S3 Storage endpoint URL
Location : cloud region of storage
Bucket : name the bucket to use for storage

Example

  Configuration Storage:
    Backend:  file
    File:
      Persistent:  true
      Volume:
        Existing Claim Name:       /acd-pvc
        Size:                      10Gi
        Storage Class Name:        <xxx>
        Supplemental Group:

`License`

Description

The License property contains two required field:

accept : must be boolean true for the ACD pods to successfully start.
use : the type of license being used. Can be one of the following values:
- Production
- Development
- ConfigurationEditor

Example

  License:
    Accept:  true
    Use:     Production

`Network Policy`

Description

The Network Policy property tells the deployment whether network security is enabled. The default is true.

Example

  Network Policy:
    Enabled:  true
    Ingress:
      From Selectors:

`Replicas`

Description

The Replicas property tells the deployment how many replica pods to create for each annotator. The default is three replicas for each annotator.

Example

  Replicas:            3

`Resources`

Description

The Resources property defines the CPU, ephemeral storage, and memory for limits and requests for the ACD service.

CPU

The default CPU request is 100m.

It is worth noting there is no limit set, so the ACD service is guaranteed its requested CPU and can use excess CPU when available.

Memory

You are able to set both requests and limits for memory. The values must follow Kubernetes constraints.

Ephemeral Storage

You are able to set the values for non-persisted or transient storage. All data created / managed within the ephemeral storage is only present for the lifetime of the pod. Transient storage should not be used as the sole storage mechanism in a production environment.

If this field is not provided, or parts of the resources object are left unset, the default values(s) will be used for the container.

Example

  Resources:
    Limits:
      Cpu:                
      Ephemeral Storage:  500Mi
      Memory:             4Gi
    Requests:
      Cpu:                100m
      Ephemeral Storage:  200Mi
      Memory:             4Gi

`Tenant Header`

Description

The Tenant Header property defines a header to include in a multi-tenant environment to isolate data from other tenants.

Example

  Tenant Header:  <AUTHORIZATION / AUTHENTICATION HEADER>

`Version`

Description

The Version property identifies the build of the operator that is deployed.

Example

  Version:  v2.0.202110010226

Status

The Annotator for Clinical Data Container Edition is a Custom Resource Definition used to deploy and manage an instance of Annotator for Clinical Data service.

Conditions

The Annotation for Clinical Data service supports Kubernetes Conditions. These Conditions can be viewed as a snapshot of the current and most up-to-date status of the instance.

The Initialized condition will be set to True when all the pods are created for the desired number of replicas set by the instance specification.

The Deployed condition will be set to InstallSuccessful when the images for the annotators have been deployed to their respective pods.

Example

$ oc get acd
NAME        INITIALIZED     DEPLOYED                VERSION             AGE
Acd-instance    True        InstallSuccessful   V2.0.20211001225        5h8m

$ oc describe acd/acd-instance
...Status:
  Conditions:
    Last Transition Time:  2021-10-05T20:38:19Z
    Status:                True

Using ACD: Software Development Kits

Using ACD: Analyzing Text