feat(provider): Complete first draft of provider docs with diagram
This commit is contained in:
parent
92a1f4c1c5
commit
3fff08f9d7
GPG key ID:
7C4D0F375BCEE533
5 changed files with 174 additions and 157 deletions
|
|
@ -11,11 +11,11 @@ description: Custom Terraform provider for orchestrating Edge deployments
|
|||
* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732)
|
||||
* **Assignee**: Martin
|
||||
* **Status**: Draft
|
||||
* **Last Updated**: YYYY-MM-DD
|
||||
* **Last Updated**: 2025-12-04
|
||||
* **TODO**:
|
||||
* [ ] Add detailed component description
|
||||
* [ ] Include usage examples and code samples
|
||||
* [ ] Add architecture diagrams
|
||||
* [x] Add detailed component description
|
||||
* [x] Include usage examples and code samples (NOTE: links to docs, rather than inline refs)
|
||||
* [x] Add architecture diagrams
|
||||
* [ ] Review and finalize content
|
||||
{{% /alert %}}
|
||||
|
||||
|
|
@ -70,74 +70,25 @@ As a result of this breadth of functionality and cross-compatibility, Terraform
|
|||
|
||||
### Verification
|
||||
|
||||
If `terraform apply` completes successfully (without errors), the provider is working correctly. You may also manually validate (in the Edge UI) that your resources have been deployed/reconfigured as Terraform indicated.
|
||||
If `terraform apply` completes successfully (without errors), the provider is working correctly. You can also manually validate in the Edge UI that your resources have been deployed/reconfigured as Terraform indicated.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### [Use Case 1]
|
||||
## Status
|
||||
|
||||
[Example with code/commands showing common use case]
|
||||
**Maturity**: Experimental
|
||||
|
||||
```bash
|
||||
# Example commands
|
||||
```
|
||||
## Additional Resources
|
||||
|
||||
### [Use Case 2]
|
||||
|
||||
[Another common scenario]
|
||||
* [Terralist](https://www.terralist.io/)
|
||||
* [Terraform](https://developer.hashicorp.com/terraform)
|
||||
* [OpenTofu](https://opentofu.org/)
|
||||
* [Edge Connect API](https://swagger.edge.platform.mg3.mdb.osc.live)
|
||||
|
||||
## Integration Points
|
||||
|
||||
* **Edge Connect SDK**: The provider uses the [Edge Connect SDK](http://localhost:1313/docs/components/deployments/edgeconnect/edgeconnect-sdk/) under the hood.
|
||||
* **Terralist**: The provider is published using a [custom instance](https://terralist.garm-provider-test.t09.de/) of [Terralist](https://www.terralist.io/). This [can only](https://edp.buildth.ing/DevFW-CICD/stacks/src/commit/5b438097bbd027f0025d6198c34c22f856392a03/template/stacks/terralist/terralist/values.yaml#L9-L38) be written to with a login via [Forgejo](https://edp.buildth.ing/), but can be accessed without such access.
|
||||
* **[Component C]**: [How it integrates]
|
||||
|
||||
## Architecture
|
||||
|
||||
[Optional: Add architectural diagrams and descriptions]
|
||||
|
||||
Terralist and its authentication
|
||||
* **Terralist**: The provider is published using a [custom instance](https://terralist.garm-provider-test.t09.de/) of [Terralist](https://www.terralist.io/). This [can only](https://edp.buildth.ing/DevFW-CICD/stacks/src/commit/5b438097bbd027f0025d6198c34c22f856392a03/template/stacks/terralist/terralist/values.yaml#L9-L38) be written to with a login via [Forgejo](https://edp.buildth.ing/), but can be read publicly.
|
||||
|
||||
### Component Architecture (C4)
|
||||
|
||||
[Add C4 Container or Component diagrams showing the internal structure]
|
||||
|
||||
### Sequence Diagrams
|
||||
|
||||
[Add sequence diagrams showing key interaction flows with other components]
|
||||
|
||||
### Deployment Architecture
|
||||
|
||||
[Add infrastructure and deployment diagrams showing how the component is deployed]
|
||||
|
||||
## Configuration
|
||||
|
||||
[Key configuration options and how to set them]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### [Common Issue 1]
|
||||
|
||||
**Problem**: [Description]
|
||||
|
||||
**Solution**: [How to fix]
|
||||
|
||||
### [Common Issue 2]
|
||||
|
||||
**Problem**: [Description]
|
||||
|
||||
**Solution**: [How to fix]
|
||||
|
||||
## Status
|
||||
|
||||
**Maturity**: [Production / Beta / Experimental]
|
||||
|
||||
## Additional Resources
|
||||
|
||||
* [Link to external documentation]
|
||||
* [Link to community resources]
|
||||
* [Link to related components]
|
||||
|
||||
## Documentation Notes
|
||||
|
||||
[Instructions for team members filling in this documentation - remove this section once complete]
|
||||
<likec4-view view-id="provider" browser="true"></likec4-view>
|
||||
|
|
|
|||
|
|
@ -85,15 +85,15 @@ specification {
|
|||
model {
|
||||
mySystem = system 'My System' {
|
||||
description 'System description'
|
||||
|
||||
|
||||
backend = service 'Backend API' {
|
||||
description 'REST API service'
|
||||
}
|
||||
|
||||
|
||||
db = database 'Database' {
|
||||
description 'PostgreSQL database'
|
||||
}
|
||||
|
||||
|
||||
backend -> db 'reads/writes'
|
||||
}
|
||||
}
|
||||
|
|
@ -101,9 +101,9 @@ model {
|
|||
views {
|
||||
view systemOverview {
|
||||
title "System Overview"
|
||||
|
||||
|
||||
include mySystem
|
||||
|
||||
|
||||
autoLayout TopBottom
|
||||
}
|
||||
}
|
||||
|
|
@ -139,7 +139,7 @@ Parameters:
|
|||
|
||||
1. **Edit Models**
|
||||
- Modify `.c4` files in `models/` or `views/`
|
||||
|
||||
|
||||
2. **Preview Changes**
|
||||
```bash
|
||||
cd resources/edp-likec4 # or doc-likec4
|
||||
|
|
@ -216,7 +216,7 @@ specification {
|
|||
element system
|
||||
element container
|
||||
element component
|
||||
|
||||
|
||||
relationship async
|
||||
relationship sync
|
||||
}
|
||||
|
|
@ -231,19 +231,19 @@ model {
|
|||
customer = person 'Customer' {
|
||||
description 'End user'
|
||||
}
|
||||
|
||||
|
||||
system = system 'My System' {
|
||||
frontend = container 'Frontend' {
|
||||
description 'React application'
|
||||
}
|
||||
|
||||
|
||||
backend = container 'Backend' {
|
||||
description 'Node.js API'
|
||||
}
|
||||
|
||||
|
||||
frontend -> backend 'API calls'
|
||||
}
|
||||
|
||||
|
||||
customer -> system.frontend 'uses'
|
||||
}
|
||||
```
|
||||
|
|
@ -256,17 +256,17 @@ Create diagrams:
|
|||
views {
|
||||
view overview {
|
||||
title "System Overview"
|
||||
|
||||
|
||||
include *
|
||||
|
||||
|
||||
autoLayout TopBottom
|
||||
}
|
||||
|
||||
|
||||
view systemDetail {
|
||||
title "System Details"
|
||||
|
||||
|
||||
include system.*
|
||||
|
||||
|
||||
autoLayout LeftRight
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
deployment {
|
||||
|
||||
cloud otc-faas 'OTC prototype FaaS' {
|
||||
description 'OTC environments for Prototype faaS.
|
||||
'
|
||||
description 'OTC environments for Prototype FaaS.'
|
||||
technology 'OTC'
|
||||
|
||||
environment dev 'tenant Dev' {
|
||||
|
|
@ -24,7 +23,7 @@ deployment {
|
|||
}
|
||||
|
||||
paas cloudServices 'EDP Cloud Services' {
|
||||
description 'EDP Cloud Services (Postgres, Redis, etc.'
|
||||
description 'EDP Cloud Services (Postgres, Redis, etc.)'
|
||||
technology 'Cloud Services'
|
||||
}
|
||||
|
||||
|
|
@ -55,7 +54,7 @@ deployment {
|
|||
|
||||
|
||||
paas cloudServices 'EDP Cloud Services' {
|
||||
description 'EDP Cloud Services (Postgres, Redis, etc.'
|
||||
description 'EDP Cloud Services (Postgres, Redis, etc.)'
|
||||
technology 'Cloud Services'
|
||||
}
|
||||
|
||||
|
|
@ -63,7 +62,6 @@ deployment {
|
|||
description '*.buildth.ing'
|
||||
icon tech:kubernetes
|
||||
technology 'Kubernetes'
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
68
resources/edp-likec4/views/deployment/edge/provider.c4
Normal file
68
resources/edp-likec4/views/deployment/edge/provider.c4
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
deployment {
|
||||
|
||||
paas edgeProvider 'Terraform Edge provider' {
|
||||
icon tech:terraform
|
||||
description "Unlocks the terraform ecosystem"
|
||||
-> edgeSdk "built using"
|
||||
-> terralist "published to"
|
||||
-> edp "hosted on"
|
||||
}
|
||||
|
||||
environment edgeProviderHost 'OTC' {
|
||||
|
||||
cluster edp 'Forgejo for all EDP-tenants' {
|
||||
icon tech:git
|
||||
instanceOf edp.forgejo 'Forgejo for all EDP-tenants' {
|
||||
description 'edp.buildth.ing'
|
||||
}
|
||||
}
|
||||
|
||||
paas terralist 'Terralist' {
|
||||
icon tech:terraform
|
||||
description 'Terraform provider private hosting'
|
||||
technology 'Cloud Services'
|
||||
-> edp "authenticates via"
|
||||
}
|
||||
}
|
||||
|
||||
paas edgeSdk 'Edge Cloud SDK' {
|
||||
icon tech:go
|
||||
description 'Wrapper around API'
|
||||
technology 'Cloud Services'
|
||||
-> edgeApi "calls"
|
||||
-> edp "hosted on"
|
||||
}
|
||||
|
||||
environment edgeCloud 'Edge cloud' {
|
||||
|
||||
paas edgeApi 'Edge Cloud API' {
|
||||
icon tech:swagger
|
||||
link https://swagger.edge.platform.mg3.mdb.osc.live "Documentation"
|
||||
technology 'Edge Cloud (managed)'
|
||||
-> edgeResources "creates/destroys"
|
||||
}
|
||||
|
||||
paas edgeResources 'Edge Cloud Resources' {
|
||||
description 'App, AppInstance, etc.'
|
||||
technology 'Edge Cloud (managed)'
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
views {
|
||||
deployment view provider {
|
||||
title 'Terraform Edge provider'
|
||||
|
||||
include
|
||||
edgeProviderHost,
|
||||
edp,
|
||||
edgeResources,
|
||||
edgeCloud,
|
||||
edgeApi,
|
||||
terralist,
|
||||
edgeSdk,
|
||||
edgeProvider,
|
||||
}
|
||||
}
|
||||
|
||||
File diff suppressed because one or more lines are too long
Loading…
Add table
Add a link
Reference in a new issue