generated SOP docs for clowder #1429
Conversation
bsquizz
left a comment
bsquizz
left a comment
There was a problem hiding this comment.
I think the doc has a better structure now. We'll need to edit a lot of the debugging/troubleshooting steps in a follow-up PR. My main concern for now is:
- All the stuff dealing with OLM can be removed
- I think a lot of stuff that is being deleted that explains how Clowder "works" should be left in, maybe under the "overview" section
docs/sop.md
Outdated
| Kafka topic, the application will be configured to use the kafka broker that has been configured in | ||
| the coupled ClowdEnvironment, which could be a local, strimzi or app-interface managed Kafka | ||
| instance. | ||
| Clowder is deployed via Operator Lifecycle Manager (OLM) with the following components: |
There was a problem hiding this comment.
We actually don't deploy it with OLM at this time. I think anything related to OLM can be removed from here for now. We simply deploy the manifest at https://github.com/RedHatInsights/clowder/blob/master/deploy.yml
| Clowder itself. | ||
| This document provides standard operating procedures for managing, debugging, and releasing Clowder - the Red Hat Insights application configuration management operator for Kubernetes. | ||
|
|
||
| Clowder utilizes a common configuration format that is presented to each application, no matter |
There was a problem hiding this comment.
I like how succinct the new doc format is, but I think a lot of this stuff that has been removed is still useful in the "overview" section. You might want to try having a different LLM rewrite these "old" sections and ask it to write them more concisely using bullet points for easier readability. I'll mark the info I think is useful to retain ...
| **abbreviated to [env] in k8s** | ||
| ## Architecture Overview | ||
|
|
||
| The ``ClowdEnvironment`` CRD is responsible for configuring key infrastruture services that the Clowder enabled |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| #### Providers | ||
| Clowder is a Kubernetes operator that manages application configuration and infrastructure dependencies for cloud-native applications. It consists of several key components: | ||
|
|
||
| An environment's specification is broken into **providers**, which govern the creation of services, e.g. Kafka topics, |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| - Reconciles ClowdApp and ClowdEnvironment resources | ||
| - Manages application lifecycle and configuration generation | ||
|
|
||
| Providers often operate in different modes. As an example the Kafka provider can operate in three |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| Applications in different ClowdApp's should not expect to be able to share databases. | ||
| ### Deployment Architecture | ||
|
|
||
| A ``ClowdApp`` is coupled to a ``ClowdEnvironment`` by the use of the ``envName`` parameter of the |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| services e.g. Kafka, or other application services such as RBAC. | ||
| ## Debugging Procedures | ||
|
|
||
| Services such as RBAC will be other Clowder-managed applications and, as such, have an associated |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| - ClowdApp resource exists but no deployments are created | ||
| - Application pods are not starting | ||
|
|
||
| Clowder creates a ``Secret`` resource that is named the same as the ``ClowdApp`` which will contain the generated configuration |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| kubectl describe clowdenvironment <env-name> | ||
| ``` | ||
|
|
||
| As stated above, promoting Clowder to production is done the same as any other app in app-interface, |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| #### Created Resources | ||
| ### Common Issues and Troubleshooting | ||
|
|
||
| For each ``ClowdApp`` service, Clowder will create an ``apps.Deployment`` and a ``Service`` |
There was a problem hiding this comment.
Keep this info (have LLM summarize if needed)
| - Manages application lifecycle and configuration generation | ||
| - Runs as a deployment in the `clowder-system` namespace | ||
|
|
||
| 2. **Custom Resource Definitions (CRDs)** |
There was a problem hiding this comment.
We should probably also mention ClowdAppRef
|
|
||
| #### Deployment Architecture | ||
|
|
||
| Clowder is deployed as a standard Kubernetes operator with the following components: |
There was a problem hiding this comment.
This seems very similar to the 'core components' section above, do you feel its duplicating things?
bsquizz
left a comment
bsquizz
left a comment
There was a problem hiding this comment.
This is a good "foundation" -- I think we have a lot more explaining to do on the areas of:
- deploy and release
- the data flow ... I think there's probably a diagram floating around out there we could insert here
- more in-depth details about "how stuff works"
But I don't think it should hold up this PR. We can work on adding those in a follow-up
2 participants
Purpose
This PR updates our SOP doc