CALM Deployments Initial Proposal

[harveymmaunders]

CALM Deployments Concept

• A CALM deployment is a representation of the state of an architecture
• Show the state of architecture deployments in terns of deployed, in progress, rolled back, completed etc as well as relevant metadata

Deployment Information

These are examples of types of information that could be stored but it will be specific and configurable to CALM users:

• HELM Charts
• Kubernetes Clusters
• Observability / dashboard links

How will this be used?

• Various different use cases, however will be focusing on the following narrative
• Deployment data is visualised through CALMHub
• User can select and architecture and select View Deployment
• This will show the status of a deployment (rollback, completed etc) as well as relevant information such as dashboard links
• Will be able to see deployment timelines
• Eventually more features, such as seeing the difference in deployment information

Initial Implementation & Design

Storing deployments related information will be an optional feature within CALM and can be implemented as follows:

• Deployment JSONs will attach directly to an architecture on a many to one mapping
• A pattern can optionally enforce a deployment schema (1:1 mapping). If an architecture owner wants to store deployment information, then it will need to be validated against the deployment schema set by the pattern owner.

Wireframes

I've mocked up a few different basic ideas on how deployment information can be used within CALMHub. There are a few more scenarios I haven't covered, e.g. an architecture does not have any deployments

Basic Deployment Information

• User can see which version of their architecture is live and which environment this architecture is for. This is on the explore section and the heading when an architecture is selected (see first question in the questions section below.
• There is a new tab Deployment for viewing deployment information for an architecture

Deployment Tab - Basic Information

• When a user selects the deployment tab, they can view information about the deployment
• Simple information includes: (this may not be all relevant but all just different ideas of information)
  • Success rate
  • Average Deployment time
  • Time since last (successful) deployment
  • Deployment ID
  • Deployment Status (in progress/successful/failed/planned)
  • Time
  • Pattern ID / Architecture ID & Version
  • There is a toggle item to see difference between this deployment and previous one (see below)

Deployment Difference

• If the user toggles the changes since last deployment section, they can see what has been changed from this deployment to the last
• For this example we can see the HELM chart has been updated and number of replicas has been changed from 3 -> 5

Observability

• A separate section of the deployment information would be links to observability / alerting dashboards

Deployment metadata

• This is a mix between some of the interface information (can be removed) and any deployment metadata a user has put in their free text blob

Deployment History

• Finally, at the bottom the user can see a history of the architecture deployments

Viewing Deployment Schema

• A user may want to see the deployment schema that is attached to a pattern
• I mocked up one way of doing this, which is to view through the pattern, although this could be namespace level alternatively

Deployment Schema

A barebones deployment JSON would be in this format

{
    "deployment-id": "",
    "architecture-id": "",
    "architecture-version": "",
    "deployment-timestamp": "",
    "deployment-status": "",
    "deployed-nodes": [
        "..."
    ],
    "deployment-data": {
        "observability-links": {
            ...
        },
        ...
    },
    "deployment-metadata": {
        "deployed-by": "",
        "deployment-environment": "",
        "rollback-available": "",
        "previous-deployment-id": "",
        "deployment-tool": "",
        "deployment-method": ""
    }
}

Using the example from the wireframes above, the JSON could look something like this:

{
    "deployment-id": "1-1.0.2-20251217103000",
    "architecture-id": "1",
    "architecture-version": "1.0.2",
    "deployment-timestamp": "2025-12-17T10:30:00Z",
    "deployment-status": "in-progress",
    "deployed-nodes": [
        "conference-website",
        "load-balancer",
        "attendees",
        "sessions",
        "feedback",
        "database"
    ],
    "deployment-data": {
        "helm-chart": "v1.2.3",
        "kubernetes-cluster": "prod-us-east-1-cluster",
        "replicas": 5,
        "observability-links": {
            "metrics-endpoint": "https://grafana.conference.example.com/d/conference-app",
            "logging-endpoint": "https://kibana.conference.example.com/app/logs",
            "tracing-endpoint": "https://jaeger.conference.example.com/search",
            "alerts-endpoint": "https://prometheus.conference.example.com/alerts"
        },
    },
    "deployment-metadata": {
        "deployed-by": "deploy-bot",
        "deployment-name": "Conference App Production Deployment",
        "deployment-environment": "production",
        "region": "us-east-1",
        "rollback-available": true,
        "previous-deployment-id": "1-1.0.1-20251210083000",
        "deployment-tool": "helm",
        "deployment-method": "rolling-update"
    }
}

CALM-Hub REST endpoints

Deployment Schema Resource

Manage deployment schemas (templates/definitions for deployments).

Operation	Endpoint	Description
POST	/deployment-schemas	Create new deployment schema
GET	/deployment-schemas/{schema-id}	Get specific deployment schema by ID
GET	/deployment-schemas	List/filter deployment schemas
PUT	/deployment-schemas/{schema-id}	Full schema update (replace entire schema)
PATCH	/deployment-schemas/{schema-id}	Partial schema update (modify specific fields)
DELETE	/deployment-schemas/{schema-id}	Delete deployment schema

Deployment Resource

Basic CRUD operations for managing deployments.

Operation	Endpoint	Description
POST	/deployments	Create new deployment
GET	/deployments/{deployment-id}	Get specific deployment by ID
GET	/deployments	List/filter deployments with query parameters
PUT	/deployments/{deployment-id}	Full deployment update (replace entire resource)
PATCH	/deployments/{deployment-id}	Partial deployment update (modify specific fields)
DELETE	/deployments/{deployment-id}	Delete deployment record
GET	/deployments/{deployment-id-1}/compare/{deployment-id-2}	Compare two deployments and return differences
PUT	/deployments/{deployment-id}/status	Update deployment status (e.g., in-progress → completed)

Architecture Resource

Architecture-specific deployment queries and history.

Operation	Endpoint	Description
GET	/architectures/{architecture-id}/deployments/timeline	Get deployment history timeline for an architecture
GET	/architectures/{architecture-id}/deployments/latest	Get most recent deployment for an architecture
GET	/architectures/{architecture-id}/deployments/stats	Get deployment statistics and metrics for an architecture

Questions

• Do we want to have deployment environment linked at all to an architecture? On the wireframes I've linked an architecture to a single environment (with the assumption that there are different architectures for different environments). We can remove the environment information if needed for the time being.
• In the design above, I've mentioned that deployments can be implemented in two different ways. A deployment schema for a pattern (1:1 mapping), where an architecture will have to validate its deployment JSON against the schema, or just have a deployment JSON for an architecture (1:many). Are we happy with this approach?
• Any feedback you have on the the following:
  • UI design
  • Deployment Schema

Next Steps

• Create CALM Deployment as a concept
• Integrate this into the CALM AI and work through ideas on deployments
• Design a simple three-tier web app and deploy to AWS. Using logs and further data, find information on what could be included on the deployment schema and identify which types of information could be stored.

[aidanm3341]

• on the example of what a deployment object would look like, I'm curious about the separation between deployment-data and deployment-metadata? Do they need to be separate? Is it a separate schema for each?
• is something like environment a data field that's mandated by the deployment schema (and therefore not aways guaranteed in every kind of deployment), or should we be opinionated and say that it's a top level field of every deployment, regardless of the schema used? If it's the former, we wouldn't be able to rely on it to display it in the UI like you have in your mockups.
• I would say that given these fields are all within a deployment object, there's no need to prefix the fields with deployment-. I.e. deployment-id can probably just be unique-id (also for consistency with other resources). deployment-status -> status.
• feels like a deployment object should have a reference to the schema that it conforms to
• I don't remember the discussion exactly now, but had we previously discussed something about an architecture deployment being defined as a list of the deployments of its constituent parts? Rather than a single overarching deployment of the entire architecture?
  • e.g. I have a deployment object for how my UI was deployed, and a separate object for how my backend was deployed. The architecture deployment is made up of both of those deployments combined. Thoughts?

[harveymmaunders]

• Regarding the difference between deployment-data and deployment-metadata; I was trying to think of a way to separate out the difference between information about the deployment and the actual deployment information (if that makes sense). This was more from the perspective of making it easier to separate out on the UI. For example regarding what HELM chart was used compared to deployment method. These would most likely be put in different places. Maybe something like this would be a better format (with deployment-data in deployment-metadata) ? Maybe deployment-data isn't the best name exactly.

{
    "deployment-id": "1-1.0.2-20251217103000",
    "architecture-id": "1",
    ...
    "deployed-nodes": [
        ...
    ],
    "deployment-metadata": {
        "deployed-by": "deploy-bot",
        "deployment-name": "Conference App Production Deployment",
        "deployment-environment": "production",
        "region": "us-east-1",
        "rollback-available": true,
        "deployment-method": "rolling-update",
        "observability-links": {
            "metrics-endpoint": "https://grafana.conference.example.com/d/conference-app",
            "logging-endpoint": "https://kibana.conference.example.com/app/logs",
            "tracing-endpoint": "https://jaeger.conference.example.com/search",
            "alerts-endpoint": "https://prometheus.conference.example.com/alerts"
        },
        "deployment-data": {
            "helm-chart": "v1.2.3",
            "kubernetes-cluster": "prod-us-east-1-cluster",
            "replicas": 5,
        },
    }
}

• Regarding the environment, I think it would be good to get the wider opinion on this. I've included it in my initial mock ups but we may not want to include at all
• I'll update my proposal for these two points (deployment names etc)
• For the last point, this is something that I realised after I'd created it. A deployment is for specific nodes but there are most likely going to be different deployments for different nodes. I'm going to update the proposal for this.