Each resource in the CAI data model is scoped either at the user or organization level. For user scoping, a user can only see resources they own. For org level scoping,
users can see any resource that belongs to their organization. The user's organization and user ID are automatically included in request headers by KAS Direct. If absent, these values default to "default".
The default scoping for most resources is user, although there are some exceptions to this. To enforce org level scoping change
the `RESOURCE_SCOPE` env var in `.env`.
### Deployments
#### 1. Cluster
All clusters are required to have org level scoping. A cluster doesn't refer to a physical K8s cluster, but rather a logical cluster. It is used to provide
some separation and organization of deployments. Currently, all deployments will run on the `compoundai` namespace. Each organization must include a cluster named default because the CLI defaults to this cluster during deployment commands.
#### 2. Deployments
Deployments are user level scoped. The `deployment` entity is used to keep track of the deployment status, K8s namespace, and other metadata. A `deployment` has
1 to n `deployment_revision`'s. Each deployment always has 1 active deployment revisions.
#### 3. Deployment Revisions
Deployment revisions are user level scoped. Each revision is owned by exactly 1 `deployment`. The `deployment_revision` is used to keep track of the history of a deployment. Each `deployment_revision` can have 1 to n `deployment_target`'s.
Each revision is marked as either active or inactive. An active deployment revision indicates that its associated targets are currently running in Kubernetes, while an inactive revision refers to terminated targets, serving primarily as historical records.
#### 4. Deployment Targets
Deployment targets are user level scoped. Each target is owned by exactly 1 `deployment` and 1 `deployment_revision`. Each `deployment_target` corresponds to a single Compound NIM instance running in Kubernetes. These entities are used when sending requests to DMS to create
any required CRDs. They keep track of important information such as the Compound NIM tag which we want to build and deploy.
### Compound NIMs
All Compound NIMs should be user scoped by default. Note: NDS v1 does not currently support user-level scoping. This functionality should be implemented during the migration from NDS v1.
##### 1. Compound NIM
This is the overarching resource that is used to keep track of a complete Compound NIM. The Compound NIM resource functions similarly to a Docker repository. For a Compound NIM tag formatted as `<name>:<tag>`, this resource represents the `<name>` portion.
A `compound_nim` resource has 1 to n `compound_nim_version`'s.
##### 1. Compound NIM Version
This is corresponds to the specific Compound NIM. Given a compound nim tag of the form `<name>:<tag>`, this resource corresponds to the `<tag>` portion. A `compound_nim_version`
The CAI is in charge of handling deployments and their metadata. Currently, any API calls
regarding a Compound NIM are proxied to and handled by NDS v1.
### Deployments
#### 1. Creating a deployment
When creating a deployment, we first create the `deployment` entity, followed by the `deployment_revision` (which is set to active), and then lastly we create all of the specified `deployment_target`'s.
After all of these entities are created, we then send 2 requests to DMS per `deployment_target`. These create a `CompoundAINimRequest` and `CompoundAINimDeployment` CRDs. We store the uid of each of these
resources within the `deployment_target`.
#### 2. Updating a deployment
We update any metadata in the `deployment` entity that is specified in the request. Following this we mark any active `deployment_revision`'s (should only be 1) as inactive. For any `deployment_target`'s that
belong to the old active revisions, we delete the `CompoundAINimRequest` and `CompoundAINimDeployment` CRDs which cause the deployment to be terminated on K8s. Following this, we create a new active `deployment_revision`,
all `deployment_target`'s, and all required `CompoundAINimRequest` and `CompoundAINimDeployment` CRDs.
#### 3. Terminating a deployment
We mark any active `deployment_revision`'s (should only be 1) as inactive. For any `deployment_target`'s that
belong to the old active revisions, we delete the `CompoundAINimRequest` and `CompoundAINimDeployment` CRDs which cause the deployment to be terminated on K8s.
#### 4. Deleting a deployment
If there is an active `deployment_revision` this request will error. Otherwise, we will delete all data models associated with a deployment including `deployment`, `deployment_revision`'s, and `deployment_target`'s.