feat(docs): restructure documentation with new framework and templates
- Archive old docs to docs-old/ for reference - Create new top-down documentation structure: * Platform Overview: purpose, audience, product structure * Components: individual platform components (Forgejo, Kubernetes, Backstage) * Getting Started: onboarding and quick start guides * Operations: deployment, monitoring, troubleshooting * Governance: ADRs, project history, compliance - Add DOCUMENTATION-GUIDE.md with writing guidelines and templates - Add component template (TEMPLATE.md) for consistent documentation - Simplify root README and move technical docs to doc/ folder - Update test configuration: * Exclude legacy content from markdown linting * Relax HTML validation for theme-generated content * Skip link checking for legacy content in test:links * Keep 'task test' clean for technical writers (100% pass) * Add 'task test:full' with comprehensive link checking - Update home page with corrected markdown syntax - Fix internal links in archived content BREAKING CHANGE: Documentation structure changed from flat to hierarchical top-down approach
This commit is contained in:
parent
2ec2efe9fc
commit
62999b41d0
196 changed files with 907 additions and 160 deletions
204
content/en/docs/DOCUMENTATION-GUIDE.md
Normal file
204
content/en/docs/DOCUMENTATION-GUIDE.md
Normal file
|
|
@ -0,0 +1,204 @@
|
|||
---
|
||||
title: "Documentation Guide"
|
||||
linkTitle: "Documentation Guide"
|
||||
weight: 100
|
||||
description: >
|
||||
Guidelines and templates for creating EDP documentation.
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This guide helps team members create consistent, high-quality documentation for the Edge Developer Platform. The documentation serves developers, engineers, and auditors who need to understand and use the platform.
|
||||
|
||||
## Documentation Principles
|
||||
|
||||
### Focus on Outcomes
|
||||
|
||||
* Describe what the platform does and how to use it
|
||||
* Emphasize practical usage over implementation details
|
||||
* Include links to repositories for deeper technical information
|
||||
|
||||
### Write for the Audience
|
||||
|
||||
* **Developers**: How to use the platform, deploy applications, integrate services
|
||||
* **Engineers**: Architecture, operational procedures, troubleshooting
|
||||
* **Auditors**: Project history, decisions, compliance information
|
||||
|
||||
### Keep It Concise
|
||||
|
||||
* Top-down approach: start with overview, drill down as needed
|
||||
* Less is more - avoid deep nested structures
|
||||
* Use templates to maintain consistency
|
||||
|
||||
### Maintain Quality
|
||||
|
||||
* Use present tense ("The system processes..." not "will process")
|
||||
* Keep information up to date
|
||||
* Test examples and procedures before documenting
|
||||
* Run `task test` before committing changes
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
The EDP documentation is organized into five main sections:
|
||||
|
||||
### 1. Platform Overview
|
||||
|
||||
High-level introduction to EDP, target audience, purpose, and product structure.
|
||||
|
||||
**Content focus**: Why EDP exists, who uses it, what it provides
|
||||
|
||||
### 2. Components
|
||||
|
||||
Detailed documentation for each platform component.
|
||||
|
||||
**Content focus**: What each component does, how to use it, integration points
|
||||
|
||||
**Template**: Use `components/TEMPLATE.md` as starting point
|
||||
|
||||
### 3. Getting Started
|
||||
|
||||
Onboarding guides and quick start instructions.
|
||||
|
||||
**Content focus**: Prerequisites, step-by-step setup, first application deployment
|
||||
|
||||
### 4. Operations
|
||||
|
||||
Deployment, monitoring, troubleshooting, and maintenance procedures.
|
||||
|
||||
**Content focus**: How to operate the platform, resolve issues, maintain health
|
||||
|
||||
### 5. Governance
|
||||
|
||||
Project history, architecture decisions, compliance, and audit information.
|
||||
|
||||
**Content focus**: Why decisions were made, project evolution, external relations
|
||||
|
||||
## Writing Documentation
|
||||
|
||||
### Using Templates
|
||||
|
||||
Templates are provided for common documentation types:
|
||||
|
||||
* **Component Documentation**: `content/en/docs/components/TEMPLATE.md`
|
||||
* Review existing component pages for examples (Forgejo, Kubernetes, Backstage)
|
||||
|
||||
### Frontmatter
|
||||
|
||||
Every markdown file starts with YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Full Page Title"
|
||||
linkTitle: "Short Nav Title"
|
||||
weight: 10
|
||||
description: >
|
||||
Brief description for search and previews.
|
||||
---
|
||||
```
|
||||
|
||||
* **title**: Full page title (appears in page header)
|
||||
* **linkTitle**: Shorter title for navigation menu
|
||||
* **weight**: Sort order (lower numbers appear first)
|
||||
* **description**: Brief summary for SEO and page previews
|
||||
|
||||
### Content Structure
|
||||
|
||||
Follow this pattern for component documentation:
|
||||
|
||||
1. **Overview**: What it is and what it does
|
||||
2. **Key Features**: Bullet list of main capabilities
|
||||
3. **Purpose in EDP**: Why it's part of the platform
|
||||
4. **Getting Started**: Quick start guide
|
||||
5. **Usage Examples**: Common scenarios
|
||||
6. **Integration Points**: How it connects to other components
|
||||
7. **Status**: Current maturity level
|
||||
8. **Documentation Notes**: Instructions for filling in details (remove when complete)
|
||||
|
||||
### Markdown Style
|
||||
|
||||
* Use `*` for bullet lists (not `-`)
|
||||
* Add blank lines around headings and lists
|
||||
* Specify language for code blocks: ` ```bash ` or ` ```yaml `
|
||||
* Use relative links for internal pages
|
||||
|
||||
### Including Code Examples
|
||||
|
||||
Always specify the language:
|
||||
|
||||
```bash
|
||||
# Good example
|
||||
task serve
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Configuration example
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
```
|
||||
|
||||
## Testing Documentation
|
||||
|
||||
Before committing changes:
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
task test
|
||||
|
||||
# Build site locally
|
||||
task build
|
||||
|
||||
# Preview changes
|
||||
task serve
|
||||
```
|
||||
|
||||
The test suite checks:
|
||||
|
||||
* Markdown syntax (markdownlint)
|
||||
* HTML validity
|
||||
* Broken links
|
||||
* Hugo build success
|
||||
|
||||
## Adding New Sections
|
||||
|
||||
When adding a new documentation section:
|
||||
|
||||
1. Create directory: `content/en/docs/[section-name]/`
|
||||
2. Create index file: `_index.md` with frontmatter
|
||||
3. Add weight to control sort order
|
||||
4. Update navigation in parent `_index.md` if needed
|
||||
5. Test with `task test`
|
||||
|
||||
## Tips for Good Documentation
|
||||
|
||||
### Do
|
||||
|
||||
* Write clearly and concisely
|
||||
* Use examples and code samples
|
||||
* Include links to repositories and external resources
|
||||
* Update documentation when features change
|
||||
* Test procedures before documenting them
|
||||
* Use templates for consistency
|
||||
|
||||
### Don't
|
||||
|
||||
* Create deep nested structures (keep it flat)
|
||||
* Document implementation details extensively (link to code instead)
|
||||
* Use future tense ("will do" → "does")
|
||||
* Add documentation for incomplete features
|
||||
* Forget to test your changes
|
||||
|
||||
## Getting Help
|
||||
|
||||
For questions about documentation:
|
||||
|
||||
* Check existing pages for examples
|
||||
* Review `doc/README-technical-writer.md` for Hugo/Docsy details
|
||||
* Ask team members for review before committing
|
||||
* Use `task serve` to preview changes locally
|
||||
|
||||
## Reference
|
||||
|
||||
* **Main README**: `/doc/README-technical-writer.md`
|
||||
* **Component Template**: `/content/en/docs/components/TEMPLATE.md`
|
||||
* **Hugo Documentation**: <https://gohugo.io/documentation/>
|
||||
* **Docsy Theme**: <https://www.docsy.dev/docs/>
|
||||
33
content/en/docs/_index.md
Executable file → Normal file
33
content/en/docs/_index.md
Executable file → Normal file
|
|
@ -1,8 +1,31 @@
|
|||
---
|
||||
title: Developer Framework Documentation
|
||||
linkTitle: Docs
|
||||
menu: {main: {weight: 20}}
|
||||
weight: 20
|
||||
title: "Documentation"
|
||||
linkTitle: "Documentation"
|
||||
menu:
|
||||
main:
|
||||
weight: 20
|
||||
---
|
||||
|
||||
This section is the project documentation for IPCEI-CIS Developer Framework.
|
||||
# Edge Developer Platform (EDP) Documentation
|
||||
|
||||
Welcome to the EDP documentation. This documentation serves developers, engineers, and auditors who want to understand, use, and audit the Edge Developer Platform.
|
||||
|
||||
## Target Audience
|
||||
|
||||
* **Developers & Engineers**: Learn how to use the platform, deploy applications, and integrate services
|
||||
* **Platform Engineers**: Understand the architecture, components, and operational aspects
|
||||
* **Auditors & Governance**: Access project history, decisions, and compliance information
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
The documentation follows a top-down approach focusing on outcomes and practical usage:
|
||||
|
||||
* **Platform Overview**: High-level introduction and product structure
|
||||
* **Components**: Individual platform components and their usage
|
||||
* **Getting Started**: Onboarding and quick start guides
|
||||
* **Operations**: Deployment, monitoring, and troubleshooting
|
||||
* **Governance**: Project history, decisions, and compliance
|
||||
|
||||
## Purpose
|
||||
|
||||
This documentation describes the outcomes and products of the edgeDeveloperFramework (eDF) project. The EDP is designed as a usable, integrated platform with clear links to repositories and implementation details.
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
---
|
||||
title: "Architecture"
|
||||
linkTitle: "Architecture"
|
||||
weight: 3
|
||||
description: >
|
||||
System architecture documentation and interactive diagrams
|
||||
---
|
||||
|
||||
This section contains architecture documentation for the IPCEI-CIS Developer Framework, including interactive C4 architecture diagrams.
|
||||
|
|
@ -1,79 +0,0 @@
|
|||
---
|
||||
title: "High Level Architecture"
|
||||
linkTitle: "High Level Architecture"
|
||||
weight: 1
|
||||
description: >
|
||||
Interactive high-level architecture overview of the Enterprise Development Platform
|
||||
---
|
||||
|
||||
This document describes the high-level architecture of our Enterprise Development Platform (EDP) system.
|
||||
|
||||
## Interactive Architecture Diagram
|
||||
|
||||
{{< likec4-view view="otc-faas" project="architecture" title="Enterprise Development Platform - OTC FaaS Deployment Architecture" >}}
|
||||
|
||||
{{< alert title="Interactive Diagram" >}}
|
||||
The diagram above is interactive when viewed in a compatible browser.
|
||||
You can click on components to explore the architecture details.
|
||||
|
||||
**Note:** The interactive diagram requires the LikeC4 webcomponent to be generated.
|
||||
See the [setup instructions]({{< ref "/docs/architecture/setup" >}}) for details.
|
||||
{{< /alert >}}
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The Enterprise Development Platform consists of several key components working together to provide a comprehensive development and deployment environment.
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **OTC Foundry** - Central management and orchestration layer
|
||||
2. **Per-Tenant EDP** - Isolated development environments for each tenant
|
||||
3. **FaaS Environment** - Function-as-a-Service deployment targets on Open Telekom Cloud
|
||||
4. **Cloud Services** - Managed services including databases, storage, and monitoring
|
||||
|
||||
### Deployment Environments
|
||||
|
||||
- **Development Environment** (`*.t09.de`) - For platform team development and testing
|
||||
- **Production Environment** (`*.buildth.ing`) - For production workloads and tenant services
|
||||
|
||||
## Component Details
|
||||
|
||||
The interactive diagram above shows the relationships between different components and how they interact within the system architecture. You can explore the diagram by clicking on different elements to see more details.
|
||||
|
||||
### Infrastructure Components
|
||||
|
||||
- **Kubernetes Clusters** - Container orchestration using OTC CCE (Cloud Container Engine)
|
||||
- **ArgoCD** - GitOps continuous deployment and application lifecycle management
|
||||
- **Forgejo** - Git repository management and CI/CD pipelines
|
||||
- **Observability Stack** - Monitoring (Prometheus, Grafana), logging (Loki), and alerting
|
||||
|
||||
### Security and Management
|
||||
|
||||
- **Keycloak** - Identity and access management (IAM)
|
||||
- **OpenBao** - Secrets management (Hashicorp Vault fork)
|
||||
- **External Secrets Operator** - Kubernetes secrets integration
|
||||
- **Crossplane** - Infrastructure as Code and cloud resource provisioning
|
||||
|
||||
### Developer Experience
|
||||
|
||||
- **Backstage** - Internal developer portal and service catalog
|
||||
- **Forgejo Actions** - CI/CD pipeline execution
|
||||
- **Development Workflows** - GitOps-based inner and outer loop workflows
|
||||
|
||||
## Setup and Maintenance
|
||||
|
||||
To update or modify the architecture diagrams:
|
||||
|
||||
1. Edit the `.c4` files in `resources/edp-likec4/`
|
||||
2. Regenerate the webcomponent:
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
npx likec4 codegen webcomponent \
|
||||
--webcomponent-prefix likec4 \
|
||||
--outfile ../../static/js/likec4-webcomponent.js
|
||||
```
|
||||
|
||||
3. Commit both the model changes and the regenerated JavaScript file
|
||||
|
||||
For more information, see the [LikeC4 Integration Guide]({{< ref "/docs/architecture/setup" >}}).
|
||||
|
|
@ -1,297 +0,0 @@
|
|||
---
|
||||
title: "LikeC4 Setup Guide"
|
||||
linkTitle: "Setup"
|
||||
weight: 10
|
||||
description: >
|
||||
How to set up and use LikeC4 interactive architecture diagrams
|
||||
---
|
||||
|
||||
This guide explains how to set up and use LikeC4 interactive architecture diagrams in this documentation.
|
||||
|
||||
## Overview
|
||||
|
||||
LikeC4 enables you to create interactive C4 architecture diagrams as code. The diagrams are defined in `.c4` files and compiled into a web component that can be embedded in any HTML page.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js (v18 or later)
|
||||
- npm or yarn
|
||||
|
||||
## Initial Setup
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
Navigate to the LikeC4 directory and install dependencies:
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Generate the Web Component
|
||||
|
||||
Create the web component that Hugo will load:
|
||||
|
||||
```bash
|
||||
npx likec4 codegen webcomponent \
|
||||
--webcomponent-prefix likec4 \
|
||||
--outfile ../../static/js/likec4-webcomponent.js
|
||||
```
|
||||
|
||||
This command:
|
||||
|
||||
- Reads all `.c4` files from `models/` and `views/`
|
||||
- Generates a single JavaScript file with all architecture views
|
||||
- Outputs to `static/js/likec4-webcomponent.js`
|
||||
|
||||
### 3. Verify Integration
|
||||
|
||||
The integration should already be configured in:
|
||||
|
||||
- `hugo.toml` - Contains `params.likec4.enable = true`
|
||||
- `layouts/partials/hooks/head-end.html` - Loads CSS and loader script
|
||||
- `static/css/likec4-styles.css` - Diagram styling
|
||||
- `static/js/likec4-loader.js` - Dynamic module loader
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```plaintext
|
||||
resources/edp-likec4/
|
||||
├── models/ # C4 model definitions
|
||||
│ ├── components/ # Component models
|
||||
│ ├── containers/ # Container models
|
||||
│ ├── context/ # System context
|
||||
│ └── code/ # Code-level workflows
|
||||
├── views/ # View definitions
|
||||
│ ├── deployment/ # Deployment views
|
||||
│ ├── edp/ # EDP views
|
||||
│ ├── high-level-concept/ # Conceptual views
|
||||
│ └── dynamic/ # Process flows
|
||||
├── package.json # Dependencies
|
||||
└── INTEGRATION.md # Integration docs
|
||||
```
|
||||
|
||||
## Using in Documentation
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Add this to any Markdown file:
|
||||
|
||||
```html
|
||||
<div class="likec4-container">
|
||||
<div class="likec4-header">
|
||||
Your Diagram Title
|
||||
</div>
|
||||
<likec4-view view-id="YOUR-VIEW-ID" browser="true"></likec4-view>
|
||||
<div class="likec4-loading" id="likec4-loading">
|
||||
Loading architecture diagram...
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Available View IDs
|
||||
|
||||
To find available view IDs, search the `.c4` files:
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
grep -r "view\s\+\w" views/ models/ --include="*.c4"
|
||||
```
|
||||
|
||||
Common views:
|
||||
|
||||
- `otc-faas` - OTC FaaS deployment
|
||||
- `edp` - EDP overview
|
||||
- `landscape` - Developer landscape
|
||||
- `edpbuilderworkflow` - Builder workflow
|
||||
- `keycloak` - Keycloak component
|
||||
|
||||
### With Hugo Alert
|
||||
|
||||
Combine with Docsy alerts for better UX:
|
||||
|
||||
```markdown
|
||||
<div class="likec4-container">
|
||||
<div class="likec4-header">
|
||||
System Architecture
|
||||
</div>
|
||||
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
|
||||
<div class="likec4-loading" id="likec4-loading">
|
||||
Loading...
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{{</* alert title="Note" */>}}
|
||||
Click on components in the diagram to explore the architecture.
|
||||
{{</* /alert */>}}
|
||||
```
|
||||
|
||||
## Workflow for Changes
|
||||
|
||||
### 1. Modify Architecture Models
|
||||
|
||||
Edit the `.c4` files in `resources/edp-likec4/`:
|
||||
|
||||
```bash
|
||||
# Edit a model
|
||||
vi resources/edp-likec4/models/containers/argocd.c4
|
||||
|
||||
# Or edit a view
|
||||
vi resources/edp-likec4/views/deployment/otc/otc-faas.c4
|
||||
```
|
||||
|
||||
### 2. Preview Changes Locally
|
||||
|
||||
Use the LikeC4 CLI to preview:
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
|
||||
# Start preview server
|
||||
npx likec4 start
|
||||
|
||||
# Opens browser at http://localhost:5173
|
||||
```
|
||||
|
||||
### 3. Regenerate Web Component
|
||||
|
||||
After making changes:
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
npx likec4 codegen webcomponent \
|
||||
--webcomponent-prefix likec4 \
|
||||
--outfile ../../static/js/likec4-webcomponent.js
|
||||
```
|
||||
|
||||
### 4. Test in Hugo
|
||||
|
||||
Start the Hugo development server:
|
||||
|
||||
```bash
|
||||
# From repository root
|
||||
hugo server -D
|
||||
|
||||
# Open http://localhost:1313
|
||||
```
|
||||
|
||||
### 5. Commit Changes
|
||||
|
||||
Commit both the model files and the regenerated web component:
|
||||
|
||||
```bash
|
||||
git add resources/edp-likec4/
|
||||
git add static/js/likec4-webcomponent.js
|
||||
git commit -m "feat: update architecture diagrams"
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Styling
|
||||
|
||||
Modify `static/css/likec4-styles.css` to customize appearance:
|
||||
|
||||
```css
|
||||
.likec4-container {
|
||||
height: 800px; /* Adjust height */
|
||||
border-radius: 8px; /* Rounder corners */
|
||||
}
|
||||
```
|
||||
|
||||
### Multiple Diagrams Per Page
|
||||
|
||||
You can include multiple diagrams on a single page:
|
||||
|
||||
```html
|
||||
<!-- First diagram -->
|
||||
<div class="likec4-container">
|
||||
<div class="likec4-header">Deployment View</div>
|
||||
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
|
||||
<div class="likec4-loading">Loading...</div>
|
||||
</div>
|
||||
|
||||
<!-- Second diagram -->
|
||||
<div class="likec4-container">
|
||||
<div class="likec4-header">Component View</div>
|
||||
<likec4-view view-id="edp" browser="true"></likec4-view>
|
||||
<div class="likec4-loading">Loading...</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Disable for Specific Pages
|
||||
|
||||
Add to page front matter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Page"
|
||||
params:
|
||||
disable_likec4: true
|
||||
---
|
||||
```
|
||||
|
||||
Then update `layouts/partials/hooks/head-end.html`:
|
||||
|
||||
```html
|
||||
{{ if and .Site.Params.likec4.enable (not .Params.disable_likec4) }}
|
||||
<!-- LikeC4 scripts -->
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Diagram Not Loading
|
||||
|
||||
1. **Check browser console** (F12 → Console)
|
||||
2. **Verify webcomponent exists:**
|
||||
|
||||
```bash
|
||||
ls -lh static/js/likec4-webcomponent.js
|
||||
```
|
||||
|
||||
3. **Regenerate if missing:**
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
npm install
|
||||
npx likec4 codegen webcomponent \
|
||||
--webcomponent-prefix likec4 \
|
||||
--outfile ../../static/js/likec4-webcomponent.js
|
||||
```
|
||||
|
||||
### View Not Found
|
||||
|
||||
- Check view ID matches exactly (case-sensitive)
|
||||
- Search for the view in `.c4` files:
|
||||
|
||||
```bash
|
||||
grep -r "view otc-faas" resources/edp-likec4/
|
||||
```
|
||||
|
||||
### Styling Issues
|
||||
|
||||
- Clear browser cache (Ctrl+Shift+R)
|
||||
- Check `static/css/likec4-styles.css` is loaded in browser DevTools → Network
|
||||
|
||||
### Build Errors
|
||||
|
||||
If LikeC4 codegen fails:
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [LikeC4 Documentation](https://likec4.dev/)
|
||||
- [C4 Model](https://c4model.com/)
|
||||
- [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
|
||||
- [Hugo Documentation](https://gohugo.io/documentation/)
|
||||
|
||||
## Migration Notes
|
||||
|
||||
This LikeC4 integration was migrated from the edp-doc repository. This repository (`ipceicis-developerframework`) is now the primary source for architecture models.
|
||||
|
||||
The edp-doc repository can reference these models via git submodule if needed.
|
||||
102
content/en/docs/components/TEMPLATE.md
Normal file
102
content/en/docs/components/TEMPLATE.md
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
title: "[Component Name]"
|
||||
linkTitle: "[Short Name]"
|
||||
weight: 99
|
||||
description: >
|
||||
[Brief one-line description of the component]
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Detailed description of the component - what it is, what it does, and why it exists]
|
||||
|
||||
## Key Features
|
||||
|
||||
* [Feature 1]
|
||||
* [Feature 2]
|
||||
* [Feature 3]
|
||||
|
||||
## Purpose in EDP
|
||||
|
||||
[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
|
||||
|
||||
## Architecture
|
||||
|
||||
[Optional: Brief architecture overview or link to detailed architecture documentation]
|
||||
|
||||
## Repository
|
||||
|
||||
**Code**: [Link to source code repository]
|
||||
|
||||
**Documentation**: [Link to component-specific documentation]
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* [Prerequisite 1]
|
||||
* [Prerequisite 2]
|
||||
|
||||
### Quick Start
|
||||
|
||||
[Step-by-step guide to get started with this component]
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
### Verification
|
||||
|
||||
[How to verify the component is working correctly]
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### [Use Case 1]
|
||||
|
||||
[Example with code/commands showing common use case]
|
||||
|
||||
```bash
|
||||
# Example commands
|
||||
```
|
||||
|
||||
### [Use Case 2]
|
||||
|
||||
[Another common scenario]
|
||||
|
||||
## Integration Points
|
||||
|
||||
* **[Component A]**: [How it integrates]
|
||||
* **[Component B]**: [How it integrates]
|
||||
* **[Component C]**: [How it integrates]
|
||||
|
||||
## 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]
|
||||
74
content/en/docs/components/_index.md
Normal file
74
content/en/docs/components/_index.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
title: "Components"
|
||||
linkTitle: "Components"
|
||||
weight: 2
|
||||
description: >
|
||||
Overview of EDP platform components and their integration.
|
||||
---
|
||||
|
||||
## Component Overview
|
||||
|
||||
The Edge Developer Platform consists of multiple integrated components. Each component serves specific purposes in the overall platform architecture.
|
||||
|
||||
This section provides detailed documentation for each component, including:
|
||||
|
||||
* Description and purpose
|
||||
* Key features and capabilities
|
||||
* Repository links and resources
|
||||
* Usage instructions and examples
|
||||
* Integration points with other components
|
||||
|
||||
## Core Components
|
||||
|
||||
### Source Code Management
|
||||
|
||||
**Forgejo**: Self-hosted Git service with repository management, issue tracking, and collaboration features.
|
||||
|
||||
**GitLab**: Enterprise-grade Git repository management with CI/CD integration.
|
||||
|
||||
### Container Orchestration
|
||||
|
||||
**Kubernetes**: Container orchestration platform for deploying and managing containerized applications.
|
||||
|
||||
### CI/CD & Automation
|
||||
|
||||
**Woodpecker**: Lightweight CI/CD server with pipeline automation.
|
||||
|
||||
**GARM**: GitHub Actions-compatible runner manager for self-hosted environments.
|
||||
|
||||
**ArgoCD**: GitOps continuous delivery tool for Kubernetes.
|
||||
|
||||
### Developer Portal
|
||||
|
||||
**Backstage**: Developer portal providing unified interface for platform services, documentation, and tooling.
|
||||
|
||||
### Observability
|
||||
|
||||
**VictoriaMetrics**: Time-series database for metrics storage and querying.
|
||||
|
||||
**Prometheus**: Metrics collection and alerting.
|
||||
|
||||
**Grafana**: Visualization and dashboards for metrics and logs.
|
||||
|
||||
### Infrastructure as Code
|
||||
|
||||
**Terraform**: Infrastructure provisioning and management.
|
||||
|
||||
**Crossplane**: Kubernetes-native infrastructure management.
|
||||
|
||||
## Component Status
|
||||
|
||||
Each component page includes current status and maturity level. Check individual component documentation for detailed information.
|
||||
|
||||
## Template for Component Documentation
|
||||
|
||||
When documenting a component, include:
|
||||
|
||||
1. **Overview**: Brief description and purpose
|
||||
2. **Key Features**: Main capabilities and use cases
|
||||
3. **Architecture**: How it fits into EDP
|
||||
4. **Getting Started**: Quick start guide
|
||||
5. **Usage Examples**: Common scenarios and patterns
|
||||
6. **Repository**: Link to source code and additional resources
|
||||
7. **Integration**: Connection points with other components
|
||||
8. **Status**: Current maturity level
|
||||
49
content/en/docs/components/backstage.md
Normal file
49
content/en/docs/components/backstage.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: "Backstage"
|
||||
linkTitle: "Backstage"
|
||||
weight: 3
|
||||
description: >
|
||||
Developer portal providing unified access to platform services and documentation.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Backstage provides a central developer portal for the EDP, offering unified access to services, documentation, and platform capabilities.
|
||||
|
||||
## Key Features
|
||||
|
||||
* Service catalog and component registry
|
||||
* Software templates for rapid application creation
|
||||
* Documentation hub
|
||||
* Kubernetes visualization
|
||||
* API documentation
|
||||
* Plugin ecosystem for extensibility
|
||||
|
||||
## Purpose in EDP
|
||||
|
||||
Backstage serves as the entry point for developers, providing discoverability of platform capabilities and streamlined workflows.
|
||||
|
||||
## Getting Started
|
||||
|
||||
[To be documented: How to access and use Backstage portal]
|
||||
|
||||
## Integration Points
|
||||
|
||||
* **Forgejo/GitLab**: Repository and CI/CD integration
|
||||
* **Kubernetes**: Resource visualization and management
|
||||
* **ArgoCD**: Deployment status and controls
|
||||
* **Documentation**: Centralized doc access
|
||||
|
||||
## Status
|
||||
|
||||
**Maturity**: Beta
|
||||
|
||||
## Documentation Notes
|
||||
|
||||
This is a template page. Team members should fill in:
|
||||
|
||||
* Access URL and authentication
|
||||
* Available plugins and features
|
||||
* Creating new components from templates
|
||||
* Service catalog usage
|
||||
* Customization options
|
||||
54
content/en/docs/components/forgejo.md
Normal file
54
content/en/docs/components/forgejo.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: "Forgejo"
|
||||
linkTitle: "Forgejo"
|
||||
weight: 1
|
||||
description: >
|
||||
Self-hosted Git service with repository management and collaboration features.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Forgejo is a self-hosted Git service that provides repository management, issue tracking, pull requests, and collaboration features. It serves as a core component of the EDP for source code management.
|
||||
|
||||
## Key Features
|
||||
|
||||
* Git repository hosting
|
||||
* Issue tracking and project management
|
||||
* Pull requests and code review
|
||||
* CI/CD integration with Woodpecker
|
||||
* User and organization management
|
||||
* API for automation and integration
|
||||
|
||||
## Purpose in EDP
|
||||
|
||||
Forgejo serves as the primary source code management platform, providing developers with a familiar Git workflow while maintaining full control over the hosting infrastructure.
|
||||
|
||||
## Repository
|
||||
|
||||
**Code**: [Link to Forgejo repository]
|
||||
|
||||
**Documentation**: [Link to Forgejo-specific documentation]
|
||||
|
||||
## Getting Started
|
||||
|
||||
[To be documented: Quick start guide for using Forgejo in EDP]
|
||||
|
||||
## Integration Points
|
||||
|
||||
* **Woodpecker CI**: Automated pipeline triggers on git events
|
||||
* **ArgoCD**: GitOps repository source
|
||||
* **Backstage**: Service catalog integration
|
||||
|
||||
## Status
|
||||
|
||||
**Maturity**: Production
|
||||
|
||||
## Documentation Notes
|
||||
|
||||
This is a template page. Team members should fill in:
|
||||
|
||||
* Specific deployment details
|
||||
* Access URLs and credentials management
|
||||
* Common workflows and usage patterns
|
||||
* Troubleshooting information
|
||||
* Screenshots or examples
|
||||
48
content/en/docs/components/kubernetes.md
Normal file
48
content/en/docs/components/kubernetes.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: "Kubernetes"
|
||||
linkTitle: "Kubernetes"
|
||||
weight: 2
|
||||
description: >
|
||||
Container orchestration platform for deploying and managing applications.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Kubernetes provides the foundation for container orchestration in the EDP, enabling deployment, scaling, and management of containerized applications.
|
||||
|
||||
## Key Features
|
||||
|
||||
* Container orchestration and scheduling
|
||||
* Service discovery and load balancing
|
||||
* Storage orchestration
|
||||
* Self-healing and automated rollouts
|
||||
* Configuration and secret management
|
||||
|
||||
## Purpose in EDP
|
||||
|
||||
Kubernetes serves as the runtime platform for all EDP components and user applications, providing standardized deployment and operations.
|
||||
|
||||
## Getting Started
|
||||
|
||||
[To be documented: Quick start for deploying to Kubernetes in EDP]
|
||||
|
||||
## Integration Points
|
||||
|
||||
* **ArgoCD**: Kubernetes deployment automation
|
||||
* **Crossplane**: Infrastructure provisioning on Kubernetes
|
||||
* **VictoriaMetrics/Prometheus**: Kubernetes metrics collection
|
||||
* **Backstage**: Kubernetes resource visualization
|
||||
|
||||
## Status
|
||||
|
||||
**Maturity**: Production
|
||||
|
||||
## Documentation Notes
|
||||
|
||||
This is a template page. Team members should fill in:
|
||||
|
||||
* Cluster access procedures
|
||||
* Namespace organization
|
||||
* Resource quotas and limits
|
||||
* Network policies
|
||||
* Storage classes and PV management
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
# CI/CD pipeline tools for composable pipeline
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
In order to build a composable pipeline that provides a golden path and reusable components, we need to define the tools that will be used to execute the pipeline.
|
||||
|
||||
ArgoCD is considered set in stone as the tool to manage the deployment of applications. However, the tools to compose and execute the pipeline are still up for debate.
|
||||
|
||||
> Note: The pipeline will use many other tools to perform certain actions such as testing, building, and deploying. This ADR is focused on the tools that will be used to compose and execute the pipeline itself.
|
||||
|
||||
In general, there are 2 decisions to make:
|
||||
|
||||
* What tools should we use to execute the pipeline?
|
||||
* What tools should we use to compose the pipeline?
|
||||
|
||||
The following use-cases should be considered for this decision:
|
||||
|
||||
* **User who wants to manage their own runners (???)**
|
||||
* User who only wants to use our golden path
|
||||
* User who wants to use our golden path and add custom actions
|
||||
* User who wants to use their own templates and import some of our actions
|
||||
* User who wants to import an existing GitHub repository with a pipeline
|
||||
|
||||
## Considered Options
|
||||
|
||||
* Argo Workflows + Events
|
||||
* Argo Workflows + Events + Additional Composition tool
|
||||
* Forgejo Actions
|
||||
* Forgejo Actions + Additional Composition tool
|
||||
* Dagger (as Engine)
|
||||
* Shuttle (as Engine)
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
TBD
|
||||
|
||||
## Pros and Cons of the Options
|
||||
|
||||
### Argo Workflows + Events
|
||||
|
||||
#### Pro
|
||||
|
||||
* integration with ArgoCD
|
||||
* ability to trigger additional workflows based on events.
|
||||
* level of maturity and community support.
|
||||
|
||||
#### Con
|
||||
|
||||
* Ability to self-host runners?
|
||||
* way how composition for pipelines works (based on Kubernetes CRDs)
|
||||
* Templates must be available in the cluster where the pipelines are executed, so any imported templates must be applied into the cluster before the pipeline can be executed and cannot simply reference a repository
|
||||
* This makes it difficult to import existing templates from other repositories when using self-hosted runners
|
||||
* This also makes it difficult to use our golden path, or at least we will need to provide a way to import our golden path into the cluster
|
||||
* This also makes the split of every component has its own repo very difficult
|
||||
* additional UI to manage the pipeline
|
||||
* Additional complexity
|
||||
|
||||
### Argo Workflows + Events + Additional Composition tool
|
||||
|
||||
#### Pro
|
||||
|
||||
* Composability can be offloaded to another tool
|
||||
|
||||
#### Con
|
||||
|
||||
* All cons of the previous option (except composability)
|
||||
* Additional complexity by adding another tool
|
||||
|
||||
### Forgejo Actions
|
||||
|
||||
#### Pro
|
||||
|
||||
* tight integration with GitHub Actions providing a familiar interface for developers and a vast catalog of actions to choose from
|
||||
* ability to compose pipelines without relying on another tool
|
||||
* Self-hosting of runners possible
|
||||
* every component can have its own repository and use different tools (e.g. written in go, bash, python etc.)
|
||||
|
||||
#### Con
|
||||
|
||||
* level of maturity - will require additional investments to provide a production-grade system
|
||||
|
||||
### Forgejo Actions + Additional Tool
|
||||
|
||||
#### Pro
|
||||
|
||||
* may be possible to use GitHub actions alongside another tool
|
||||
|
||||
#### Con
|
||||
|
||||
* additional complexity by adding another tool
|
||||
|
||||
### Shuttle
|
||||
|
||||
#### Pro
|
||||
|
||||
* Possibility to clearly define interfaces for pipeline steps
|
||||
* Relatively simple
|
||||
|
||||
#### Con
|
||||
|
||||
* basically backed by only one company
|
||||
* **centralized templates**, so no mechanism for composing pipelines from multiple repositories
|
||||
|
||||
### Dagger
|
||||
|
||||
#### Pro
|
||||
|
||||
* Pipeline as code
|
||||
* if it runs it should run anywhere and produce the "same" / somewhat stable results
|
||||
* build environments are defined within containers / the dagger config. Dagger is the only dependency one has to install on a machine
|
||||
* DX is extremely nice, especially if you have to debug (image) builds, also type safety due to the ability to code your build in a strong language
|
||||
* additional tooling, like trivy, is added to a build pipeline with low effort due to containers and existing plugin/wrappers
|
||||
* you can create complex test environments similar to test containers and docker compose
|
||||
|
||||
#### Con
|
||||
|
||||
* relies heavily containers, which might not be available some environments (due to policy etc), it also has an effect on reproducibility and verifiability
|
||||
* as a dev you need to properly understand containers
|
||||
* dagger engine has to run privileged locally and/or in the cloud which might be a blocker or at least a big pain in the ...
|
||||
|
||||
#### Suggestion Patrick
|
||||
|
||||
* dagger is a heavy weight and might not be as productive in a dev workflow as it seems (setup lsp etc)
|
||||
* it might be too opinionated to force on teams, especially since it is not near mainstream enough, community might be too small
|
||||
* it feels like dagger gets you 95% of the way, but the remaining 5% are a real struggle
|
||||
* if we like it, we should check the popularity in the dev community before further considering as it has a direct impact on teams and their preferences
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
# ADRs
|
||||
|
||||
Architecture Decision Records (ADRs) are a way to capture the important architectural decisions made during the development of a project. They are a way to document the context, the decision, and the consequences of the decision. They are a way to keep track of the architectural decisions made in a project and to communicate them to the team.
|
||||
|
||||
The [Markdown Architectural Decision Records](https://adr.github.io/madr/) (MADR) format is a simple and easy-to-use format for writing ADRs in Markdown.
|
||||
|
|
@ -1,67 +0,0 @@
|
|||
<!-- we need to disable MD025, because we use the different heading "ADR Template" in the homepage (see above) than it is foreseen in the template -->
|
||||
<!-- markdownlint-disable-next-line MD025 -->
|
||||
# {short title, representative of solved problem and found solution}
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
|
||||
|
||||
<!-- This is an optional element. Feel free to remove. -->
|
||||
## Decision Drivers
|
||||
|
||||
* {decision driver 1, e.g., a force, facing concern, …}
|
||||
* {decision driver 2, e.g., a force, facing concern, …}
|
||||
* … <!-- numbers of drivers can vary -->
|
||||
|
||||
## Considered Options
|
||||
|
||||
* {title of option 1}
|
||||
* {title of option 2}
|
||||
* {title of option 3}
|
||||
* … <!-- numbers of options can vary -->
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
|
||||
|
||||
<!-- This is an optional element. Feel free to remove. -->
|
||||
### Consequences
|
||||
|
||||
* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
|
||||
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
|
||||
* … <!-- numbers of consequences can vary -->
|
||||
|
||||
<!-- This is an optional element. Feel free to remove. -->
|
||||
### Confirmation
|
||||
|
||||
{Describe how the implementation of/compliance with the ADR can/will be confirmed. Are the design that was decided for and its implementation in line with the decision made? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Not that although we classify this element as optional, it is included in many ADRs.}
|
||||
|
||||
<!-- This is an optional element. Feel free to remove. -->
|
||||
## Pros and Cons of the Options
|
||||
|
||||
### {title of option 1}
|
||||
|
||||
<!-- This is an optional element. Feel free to remove. -->
|
||||
{example | description | pointer to more information | …}
|
||||
|
||||
* Good, because {argument a}
|
||||
* Good, because {argument b}
|
||||
<!-- use "neutral" if the given argument weights neither for good nor bad -->
|
||||
* Neutral, because {argument c}
|
||||
* Bad, because {argument d}
|
||||
* … <!-- numbers of pros and cons can vary -->
|
||||
|
||||
### {title of other option}
|
||||
|
||||
{example | description | pointer to more information | …}
|
||||
|
||||
* Good, because {argument a}
|
||||
* Good, because {argument b}
|
||||
* Neutral, because {argument c}
|
||||
* Bad, because {argument d}
|
||||
* …
|
||||
|
||||
<!-- This is an optional element. Feel free to remove. -->
|
||||
## More Information
|
||||
|
||||
{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
---
|
||||
title: "Documentation About Documentation"
|
||||
linkTitle: "Documentation"
|
||||
weight: 10
|
||||
description: >
|
||||
Learn how to create, maintain, and publish documentation for the developer platform.
|
||||
---
|
||||
|
||||
Welcome to the meta-documentation! This section explains how our documentation platform works and guides you through the technicalWriter role.
|
||||
|
||||
## What is a Technical Writer?
|
||||
|
||||
A **Technical Writer** is responsible for creating, maintaining, and publishing the developer platform documentation. This includes:
|
||||
|
||||
- Writing and updating content in Markdown
|
||||
- Creating architecture diagrams with LikeC4
|
||||
- Testing locally before committing
|
||||
- Following the CI/CD pipeline to production
|
||||
|
||||
## Documentation Platform Architecture
|
||||
|
||||
Our documentation is built on a modern stack:
|
||||
|
||||
- **Hugo** with the **Docsy** theme for static site generation
|
||||
- **LikeC4** for architecture visualization
|
||||
- **Taskfile** for local development automation
|
||||
- **GitHub Actions** for continuous testing
|
||||
- **Edge deployment** for hosting
|
||||
|
||||
### System Overview
|
||||
|
||||
{{< likec4-view view="overview" project="documentation-platform" >}}
|
||||
|
||||
This high-level view shows all major components of the documentation platform.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Continue to the next sections to learn about:
|
||||
|
||||
1. [Local Development](local-development/) - How to work on documentation locally
|
||||
2. [Testing](testing/) - Quality assurance processes
|
||||
3. [CI/CD Pipeline](cicd/) - Automated testing and deployment
|
||||
4. [Publishing](publishing/) - How documentation reaches production
|
||||
|
|
@ -1,264 +0,0 @@
|
|||
---
|
||||
title: "CI/CD Pipeline"
|
||||
linkTitle: "CI/CD"
|
||||
weight: 40
|
||||
description: >
|
||||
Automated testing and container build process.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Our documentation uses a continuous integration and deployment pipeline to ensure quality and automate deployment.
|
||||
|
||||
{{< likec4-view view="cicdPipeline" project="documentation-platform" >}}
|
||||
|
||||
## GitHub Actions Workflow
|
||||
|
||||
The CI/CD pipeline is defined in `.github/workflows/test.yml` and runs on:
|
||||
|
||||
- **Pushes to `main` branch**
|
||||
- **Pull requests to `main` branch**
|
||||
|
||||
### Workflow Steps
|
||||
|
||||
#### 1. Checkout Code
|
||||
|
||||
```yaml
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
fetch-depth: 0
|
||||
```
|
||||
|
||||
- Clones repository with full history
|
||||
- Includes Git submodules (Hugo modules)
|
||||
|
||||
#### 2. Setup Hugo
|
||||
|
||||
```yaml
|
||||
- name: Setup Hugo
|
||||
uses: peaceiris/actions-hugo@v3
|
||||
with:
|
||||
hugo-version: 'latest'
|
||||
extended: true
|
||||
```
|
||||
|
||||
- Installs Hugo Extended
|
||||
- Uses latest stable version
|
||||
|
||||
#### 3. Setup Node.js
|
||||
|
||||
```yaml
|
||||
- name: Setup Node
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '24'
|
||||
cache: 'npm'
|
||||
```
|
||||
|
||||
- Installs Node.js v24
|
||||
- Caches npm dependencies for faster builds
|
||||
|
||||
#### 4. Install Dependencies
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
go install github.com/wjdp/htmltest@latest
|
||||
```
|
||||
|
||||
- Installs npm packages (markdownlint, htmlvalidate)
|
||||
- Installs htmltest for link checking
|
||||
|
||||
#### 5. Run Tests
|
||||
|
||||
```bash
|
||||
npm run test:build
|
||||
npm run test:markdown
|
||||
npm run test:html
|
||||
```
|
||||
|
||||
- Validates Hugo build
|
||||
- Lints Markdown files
|
||||
- Validates HTML output
|
||||
|
||||
#### 6. Link Checking
|
||||
|
||||
```yaml
|
||||
- name: Run link checker
|
||||
run: htmltest
|
||||
continue-on-error: true
|
||||
```
|
||||
|
||||
- Checks all links
|
||||
- Continues even if links fail (soft requirement)
|
||||
|
||||
#### 7. Upload Results
|
||||
|
||||
```yaml
|
||||
- name: Upload htmltest results
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: htmltest-report
|
||||
path: tmp/.htmltest/
|
||||
```
|
||||
|
||||
- Uploads link check report
|
||||
- Available for download from GitHub Actions
|
||||
|
||||
## Container Build Process
|
||||
|
||||
After tests pass, a container image is built:
|
||||
|
||||
```bash
|
||||
task build:oci-image
|
||||
```
|
||||
|
||||
### Build Process
|
||||
|
||||
1. **Reads version information** from `.env.versions`:
|
||||
- `NODE_VERSION`
|
||||
- `GO_VERSION`
|
||||
- `HUGO_VERSION`
|
||||
|
||||
2. **Builds Docker image** using `Dockerfile`:
|
||||
- Multi-stage build
|
||||
- Hugo generates static site
|
||||
- Nginx serves the content
|
||||
|
||||
3. **Tags image** with:
|
||||
- `latest`
|
||||
- Git commit SHA (short)
|
||||
|
||||
### Dockerfile Structure
|
||||
|
||||
```dockerfile
|
||||
# Build stage
|
||||
FROM node:${NODE_VERSION} as builder
|
||||
# Install Hugo, build dependencies
|
||||
# Run: hugo --gc --minify
|
||||
# Output: public/ directory
|
||||
|
||||
# Runtime stage
|
||||
FROM nginx:alpine
|
||||
# Copy public/ to /usr/share/nginx/html/
|
||||
# Configure Nginx
|
||||
```
|
||||
|
||||
### Testing the Container
|
||||
|
||||
```bash
|
||||
task test:oci-image
|
||||
```
|
||||
|
||||
This:
|
||||
|
||||
1. Builds the image
|
||||
2. Starts container on port 8080
|
||||
3. Tests HTTP endpoint
|
||||
4. Cleans up container
|
||||
|
||||
## Package.json Scripts
|
||||
|
||||
The `package.json` defines test scripts:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test:build": "hugo --gc --minify --logLevel info",
|
||||
"test:markdown": "markdownlint 'content/**/*.md'",
|
||||
"test:html": "htmlvalidate 'public/**/*.html'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Running CI Locally
|
||||
|
||||
Simulate the CI environment locally:
|
||||
|
||||
```bash
|
||||
task ci
|
||||
```
|
||||
|
||||
This runs the same tests as GitHub Actions.
|
||||
|
||||
## Monitoring CI Results
|
||||
|
||||
### Successful Build
|
||||
|
||||
✅ All tests pass → Ready to deploy
|
||||
|
||||
### Failed Build
|
||||
|
||||
❌ Tests fail:
|
||||
|
||||
1. Click on the failed workflow in GitHub Actions
|
||||
2. Expand the failed step
|
||||
3. Read the error message
|
||||
4. Fix locally: `task test:<specific-test>`
|
||||
5. Commit and push fix
|
||||
|
||||
### Viewing Artifacts
|
||||
|
||||
1. Go to GitHub Actions
|
||||
2. Click on workflow run
|
||||
3. Scroll to "Artifacts" section
|
||||
4. Download `htmltest-report`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Don't push to main directly** - Use feature branches and PRs
|
||||
2. **Wait for CI before merging** - Green checkmark required
|
||||
3. **Fix broken builds immediately** - Don't let main stay red
|
||||
4. **Review CI logs** - Understand why tests fail
|
||||
5. **Update dependencies** - Keep versions current in `.env.versions`
|
||||
|
||||
## Continuous Deployment
|
||||
|
||||
After successful CI:
|
||||
|
||||
1. Container image is built
|
||||
2. Image is pushed to registry
|
||||
3. Deployment process begins (see [Publishing](../publishing/))
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tests pass locally but fail in CI
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
- Different Hugo version
|
||||
- Different Node.js version
|
||||
- Missing dependencies
|
||||
- Environment-specific issues
|
||||
|
||||
**Solution:** Check versions in `.env.versions` and ensure local matches CI
|
||||
|
||||
### Build timeouts
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
- Link checker taking too long
|
||||
- Large number of external links
|
||||
|
||||
**Solution:**
|
||||
|
||||
- Use `continue-on-error: true` for link checks
|
||||
- Configure `.htmltest.yml` to skip slow checks
|
||||
|
||||
### Cache issues
|
||||
|
||||
**Solution:** Clear GitHub Actions cache:
|
||||
|
||||
```yaml
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
path: ~/.npm
|
||||
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
|
||||
```
|
||||
|
||||
Update the cache key to force refresh.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Learn about [deployment to Edge environment](../publishing/).
|
||||
|
|
@ -1,234 +0,0 @@
|
|||
---
|
||||
title: "Local Development"
|
||||
linkTitle: "Local Development"
|
||||
weight: 20
|
||||
description: >
|
||||
Set up your local environment and learn the technicalWriter workflow.
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, ensure you have:
|
||||
|
||||
- **Devbox** or the following tools installed:
|
||||
- Hugo Extended (latest version)
|
||||
- Node.js (v24+)
|
||||
- Go (for htmltest)
|
||||
- Git
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd ipceicis-developerframework
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
|
||||
```bash
|
||||
task deps:install
|
||||
```
|
||||
|
||||
3. **If using Devbox**, enter the Devbox shell:
|
||||
|
||||
```bash
|
||||
devbox shell
|
||||
```
|
||||
|
||||
This ensures all tools (Hugo, Node.js, Go) are available in the correct versions.
|
||||
|
||||
## Local Development Workflow
|
||||
|
||||
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}
|
||||
|
||||
### Starting the Development Server
|
||||
|
||||
The easiest way to work locally is to start the Hugo development server:
|
||||
|
||||
```bash
|
||||
task serve
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Generate build information (git commit, version)
|
||||
- Start Hugo server on `http://localhost:1313`
|
||||
- Enable hot reload - changes appear instantly in the browser
|
||||
|
||||
### Content Structure
|
||||
|
||||
```text
|
||||
content/
|
||||
└── en/ # English content
|
||||
├── _index.md # Homepage
|
||||
├── blog/ # Blog posts
|
||||
└── docs/ # Documentation
|
||||
├── architecture/ # Architecture docs
|
||||
├── decisions/ # ADRs
|
||||
└── v1/ # Version-specific docs
|
||||
```
|
||||
|
||||
### Creating Content
|
||||
|
||||
1. **Add a new documentation page:**
|
||||
|
||||
```bash
|
||||
# Create a new markdown file
|
||||
vim content/en/docs/your-topic/_index.md
|
||||
```
|
||||
|
||||
2. **Add frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Your Topic"
|
||||
linkTitle: "Your Topic"
|
||||
weight: 10
|
||||
description: >
|
||||
Brief description of your topic.
|
||||
---
|
||||
```
|
||||
|
||||
3. **Write your content** in Markdown
|
||||
|
||||
4. **Preview changes** - they appear immediately if `task serve` is running
|
||||
|
||||
### Creating Architecture Diagrams
|
||||
|
||||
Architecture diagrams are created with LikeC4:
|
||||
|
||||
1. **Navigate to the appropriate LikeC4 project:**
|
||||
- `resources/edp-likec4/` - Platform architecture
|
||||
- `resources/doc-likec4/` - Documentation platform architecture
|
||||
|
||||
2. **Edit or create `.c4` files** with your model
|
||||
|
||||
Example: Create a simple view in `resources/edp-likec4/views/my-view.c4`:
|
||||
|
||||
```likec4
|
||||
specification {
|
||||
element myperson
|
||||
element mysystem
|
||||
}
|
||||
|
||||
model {
|
||||
customer = myperson 'Customer' {
|
||||
description 'End user of the platform'
|
||||
}
|
||||
|
||||
mySystem = mysystem 'My System' {
|
||||
description 'Example system component'
|
||||
}
|
||||
|
||||
customer -> mySystem 'uses'
|
||||
}
|
||||
|
||||
views {
|
||||
view myCustomView {
|
||||
title "My Custom Architecture View"
|
||||
|
||||
include customer
|
||||
include mySystem
|
||||
|
||||
autoLayout TopBottom
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Regenerate webcomponents:**
|
||||
|
||||
```bash
|
||||
task likec4:generate
|
||||
```
|
||||
|
||||
4. **Embed diagrams in Markdown:**
|
||||
|
||||
```markdown
|
||||
{{</* likec4-view view="myCustomView" project="architecture" title="My Custom Architecture View" */>}}
|
||||
```
|
||||
|
||||
**Finding available view IDs:**
|
||||
- Open the `.c4` files in your project directory
|
||||
- Look for `view <viewId> {` declarations
|
||||
- The `<viewId>` is what you use in the `view` parameter
|
||||
- Or use: `grep -r "^view " resources/edp-likec4/ --include="*.c4"`
|
||||
|
||||
## Available Tasks
|
||||
|
||||
View all available tasks:
|
||||
|
||||
```bash
|
||||
task --list
|
||||
```
|
||||
|
||||
### Common Development Tasks
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| `task serve` | Start development server with hot reload |
|
||||
| `task build` | Build production-ready site |
|
||||
| `task build:dev` | Build development version |
|
||||
| `task clean` | Remove build artifacts |
|
||||
| `task test` | Run all tests |
|
||||
| `task test:quick` | Run tests without link checking |
|
||||
|
||||
## Quick Testing
|
||||
|
||||
Before committing, run quick tests:
|
||||
|
||||
```bash
|
||||
task test:quick
|
||||
```
|
||||
|
||||
This validates:
|
||||
|
||||
- Hugo build succeeds
|
||||
- Markdown syntax is correct
|
||||
|
||||
For comprehensive testing, including link checking:
|
||||
|
||||
```bash
|
||||
task test
|
||||
```
|
||||
|
||||
## Tips for Technical Writers
|
||||
|
||||
1. **Write in present tense** - "The system processes..." not "The system will process..."
|
||||
2. **Use code blocks** with syntax highlighting
|
||||
3. **Include diagrams** for complex concepts
|
||||
4. **Test locally** before pushing
|
||||
5. **Keep it concise** - readers appreciate brevity
|
||||
6. **Update regularly** - stale docs are worse than no docs
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port 1313 already in use
|
||||
|
||||
```bash
|
||||
# Find and kill the process
|
||||
lsof -ti:1313 | xargs kill -9
|
||||
```
|
||||
|
||||
### Build errors
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
task clean
|
||||
task build:dev
|
||||
```
|
||||
|
||||
### Missing dependencies
|
||||
|
||||
```bash
|
||||
# Reinstall all dependencies
|
||||
task deps:install
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you can develop locally, learn about:
|
||||
|
||||
- [Testing processes](../testing/)
|
||||
- [CI/CD pipeline](../cicd/)
|
||||
|
|
@ -1,339 +0,0 @@
|
|||
---
|
||||
title: "Publishing to Edge"
|
||||
linkTitle: "Publishing"
|
||||
weight: 50
|
||||
description: >
|
||||
How documentation is deployed to the edge environment.
|
||||
---
|
||||
|
||||
## Deployment Overview
|
||||
|
||||
After successful CI/CD, the documentation is deployed to an edge computing environment.
|
||||
|
||||
{{< likec4-view view="deploymentFlow" project="documentation-platform" >}}
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Edge Connect Platform
|
||||
|
||||
Our documentation is deployed using **Edge Connect**, which orchestrates deployments to edge cloudlets.
|
||||
|
||||
Configuration: `edgeconnectdeployment.yaml`
|
||||
|
||||
```yaml
|
||||
kind: edgeconnect-deployment
|
||||
metadata:
|
||||
name: "edpdoc"
|
||||
appVersion: "1.0.0"
|
||||
organization: "edp2"
|
||||
spec:
|
||||
k8sApp:
|
||||
manifestFile: "./k8s-deployment.yaml"
|
||||
infraTemplate:
|
||||
- region: "EU"
|
||||
cloudletOrg: "TelekomOP"
|
||||
cloudletName: "Munich"
|
||||
flavorName: "EU.small"
|
||||
```
|
||||
|
||||
**Key settings:**
|
||||
|
||||
- **Deployment name:** `edpdoc`
|
||||
- **Region:** EU (Munich)
|
||||
- **Cloudlet:** TelekomOP Munich
|
||||
- **Flavor:** EU.small (resource allocation)
|
||||
|
||||
### Kubernetes Deployment
|
||||
|
||||
The application runs on Kubernetes: `k8s-deployment.yaml`
|
||||
|
||||
#### Service Definition
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: edpdoc
|
||||
labels:
|
||||
run: edpdoc
|
||||
spec:
|
||||
type: LoadBalancer
|
||||
ports:
|
||||
- name: tcp80
|
||||
protocol: TCP
|
||||
port: 80
|
||||
targetPort: 80
|
||||
selector:
|
||||
run: edpdoc
|
||||
```
|
||||
|
||||
- **Type:** LoadBalancer (external access)
|
||||
- **Port:** 80 (HTTP)
|
||||
- **Selector:** Routes traffic to pods with label `run: edpdoc`
|
||||
|
||||
#### Deployment Configuration
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: edpdoc
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
run: edpdoc
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
run: edpdoc
|
||||
mexDeployGen: kubernetes-basic
|
||||
spec:
|
||||
containers:
|
||||
- name: edpdoc
|
||||
image: ###IMAGETAG###
|
||||
imagePullPolicy: Always
|
||||
ports:
|
||||
- containerPort: 80
|
||||
protocol: TCP
|
||||
```
|
||||
|
||||
- **Replicas:** 1 (single instance)
|
||||
- **Image:** Injected by deployment pipeline (`###IMAGETAG###` placeholder)
|
||||
- **Pull policy:** Always (ensures latest version)
|
||||
|
||||
### Network Configuration
|
||||
|
||||
Outbound connections are configured in `edgeconnectdeployment.yaml`:
|
||||
|
||||
```yaml
|
||||
network:
|
||||
outboundConnections:
|
||||
- protocol: "tcp"
|
||||
portRangeMin: 80
|
||||
portRangeMax: 80
|
||||
remoteCIDR: "0.0.0.0/0"
|
||||
- protocol: "tcp"
|
||||
portRangeMin: 443
|
||||
portRangeMax: 443
|
||||
remoteCIDR: "0.0.0.0/0"
|
||||
```
|
||||
|
||||
- **Port 80:** HTTP outbound
|
||||
- **Port 443:** HTTPS outbound
|
||||
- **CIDR:** `0.0.0.0/0` (all destinations)
|
||||
|
||||
## Deployment Process
|
||||
|
||||
### 1. Container Image Ready
|
||||
|
||||
After CI passes:
|
||||
|
||||
- Docker image built with `task build:oci-image`
|
||||
- Tagged with git commit SHA
|
||||
- Pushed to container registry
|
||||
|
||||
### 2. Edge Connect Orchestration
|
||||
|
||||
Edge Connect:
|
||||
|
||||
1. Pulls container image
|
||||
2. Reads `edgeconnectdeployment.yaml`
|
||||
3. Provisions resources on Munich cloudlet
|
||||
4. Applies Kubernetes manifests
|
||||
|
||||
### 3. Kubernetes Deployment
|
||||
|
||||
Kubernetes:
|
||||
|
||||
1. Creates deployment with 1 replica
|
||||
2. Pulls container image (`imagePullPolicy: Always`)
|
||||
3. Starts pod running Nginx + static Hugo site
|
||||
4. Creates LoadBalancer service
|
||||
5. Assigns external IP
|
||||
|
||||
### 4. Service Available
|
||||
|
||||
Documentation is now accessible:
|
||||
|
||||
- **Protocol:** HTTP
|
||||
- **Port:** 80
|
||||
- **IP:** Assigned by LoadBalancer
|
||||
|
||||
## Complete Workflow
|
||||
|
||||
{{< likec4-view view="fullWorkflow" project="documentation-platform" >}}
|
||||
|
||||
### End-to-End Process
|
||||
|
||||
1. **Technical Writer writes content** (Markdown, LikeC4 models)
|
||||
2. **Local testing** with `task serve` and `task test`
|
||||
3. **Commit and push** to Git repository
|
||||
4. **GitHub Actions triggered** on push to main
|
||||
5. **CI tests run** (build, markdown, HTML, links)
|
||||
6. **Container image built** if tests pass
|
||||
7. **Image pushed** to registry
|
||||
8. **Edge deployment triggered**
|
||||
9. **Kubernetes applies** manifests
|
||||
10. **Service available** on edge cloudlet
|
||||
|
||||
## Monitoring Deployment
|
||||
|
||||
### Check Deployment Status
|
||||
|
||||
```bash
|
||||
kubectl get deployments -n <namespace>
|
||||
kubectl get pods -n <namespace>
|
||||
kubectl get services -n <namespace>
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
kubectl logs deployment/edpdoc -n <namespace>
|
||||
```
|
||||
|
||||
### Access Documentation
|
||||
|
||||
Find the LoadBalancer external IP:
|
||||
|
||||
```bash
|
||||
kubectl get service edpdoc -n <namespace>
|
||||
```
|
||||
|
||||
Access via: `http://<EXTERNAL-IP>`
|
||||
|
||||
## Rollback
|
||||
|
||||
If issues occur after deployment:
|
||||
|
||||
### Option 1: Revert Commit
|
||||
|
||||
```bash
|
||||
git revert <bad-commit>
|
||||
git push origin main
|
||||
```
|
||||
|
||||
CI will rebuild and redeploy.
|
||||
|
||||
### Option 2: Manual Rollback
|
||||
|
||||
```bash
|
||||
kubectl rollout undo deployment/edpdoc -n <namespace>
|
||||
```
|
||||
|
||||
Returns to previous deployment version.
|
||||
|
||||
### Option 3: Deploy Specific Version
|
||||
|
||||
Update image tag in deployment:
|
||||
|
||||
```bash
|
||||
kubectl set image deployment/edpdoc edpdoc=<registry>/<image>:<tag> -n <namespace>
|
||||
```
|
||||
|
||||
## Scaling
|
||||
|
||||
Currently: **1 replica**
|
||||
|
||||
To scale for higher traffic:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
replicas: 3
|
||||
```
|
||||
|
||||
Then apply:
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s-deployment.yaml
|
||||
```
|
||||
|
||||
Or scale dynamically:
|
||||
|
||||
```bash
|
||||
kubectl scale deployment/edpdoc --replicas=3 -n <namespace>
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Image scanning** - Scan container images for vulnerabilities
|
||||
2. **Resource limits** - Set CPU/memory limits in deployment
|
||||
3. **Network policies** - Restrict pod-to-pod communication
|
||||
4. **HTTPS** - Consider adding TLS termination (Ingress)
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
1. **CDN** - Add CDN in front of LoadBalancer
|
||||
2. **Caching** - Configure Nginx caching headers
|
||||
3. **Compression** - Enable gzip in Nginx
|
||||
4. **Image optimization** - Compress images in documentation
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pod not starting
|
||||
|
||||
```bash
|
||||
kubectl describe pod <pod-name> -n <namespace>
|
||||
```
|
||||
|
||||
Check:
|
||||
|
||||
- Image pull errors
|
||||
- Resource constraints
|
||||
- Configuration errors
|
||||
|
||||
### Service unreachable
|
||||
|
||||
```bash
|
||||
kubectl describe service edpdoc -n <namespace>
|
||||
```
|
||||
|
||||
Check:
|
||||
|
||||
- LoadBalancer IP assigned
|
||||
- Port configuration
|
||||
- Network policies
|
||||
|
||||
### Old content served
|
||||
|
||||
Check:
|
||||
|
||||
- `imagePullPolicy: Always` in deployment
|
||||
- Image tag is updated
|
||||
- Pod has restarted
|
||||
|
||||
Force pod restart:
|
||||
|
||||
```bash
|
||||
kubectl rollout restart deployment/edpdoc -n <namespace>
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Test before deploying** - Always run `task test` locally
|
||||
2. **Use feature branches** - Don't deploy directly from local
|
||||
3. **Monitor after deployment** - Check logs and access
|
||||
4. **Document changes** - Update RELEASE.md
|
||||
5. **Version control** - Tag releases in Git
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
|
||||
- **Blue-green deployment** - Zero-downtime updates
|
||||
- **Canary releases** - Gradual rollout to subset of users
|
||||
- **Auto-scaling** - HorizontalPodAutoscaler based on traffic
|
||||
- **Multi-region** - Deploy to multiple cloudlets
|
||||
- **HTTPS** - TLS certificates and Ingress controller
|
||||
|
||||
## Summary
|
||||
|
||||
The deployment process is automated and reliable:
|
||||
|
||||
✅ **CI ensures quality** - Tests prevent broken deployments
|
||||
✅ **Edge infrastructure** - Low-latency access from EU
|
||||
✅ **Kubernetes orchestration** - Reliable, scalable platform
|
||||
✅ **Simple rollback** - Easy to recover from issues
|
||||
|
||||
As a technicalWriter, focus on content quality. The platform handles deployment automatically! 🚀
|
||||
|
|
@ -1,282 +0,0 @@
|
|||
---
|
||||
title: "Quick Reference"
|
||||
linkTitle: "Quick Reference"
|
||||
weight: 60
|
||||
description: >
|
||||
Cheat sheet for common technicalWriter tasks.
|
||||
---
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Start development server (with hot reload)
|
||||
task serve
|
||||
|
||||
# Build for production
|
||||
task build
|
||||
|
||||
# Build for development (faster, no minification)
|
||||
task build:dev
|
||||
|
||||
# Clean build artifacts
|
||||
task clean
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Quick tests (build + markdown)
|
||||
task test:quick
|
||||
|
||||
# Full test suite
|
||||
task test
|
||||
|
||||
# Individual tests
|
||||
task test:build # Hugo build validation
|
||||
task test:markdown # Markdown linting
|
||||
task test:html # HTML validation
|
||||
task test:links # Link checking
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
task deps:install
|
||||
|
||||
# Update dependencies
|
||||
task deps:update
|
||||
|
||||
# Ensure npm dependencies (auto-installs if missing)
|
||||
task deps:ensure-npm
|
||||
```
|
||||
|
||||
### Container Operations
|
||||
|
||||
```bash
|
||||
# Build OCI/Docker image
|
||||
task build:oci-image
|
||||
|
||||
# Build and test container
|
||||
task test:oci-image
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
### Content
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `content/en/docs/` | Main documentation |
|
||||
| `content/en/blog/` | Blog posts |
|
||||
| `content/en/_index.md` | Homepage |
|
||||
|
||||
### Architecture Models
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `resources/edp-likec4/` | Platform architecture models |
|
||||
| `resources/doc-likec4/` | Documentation platform models |
|
||||
|
||||
### Configuration
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `hugo.toml` | Hugo configuration |
|
||||
| `config.yaml` | Docsy theme config |
|
||||
| `Taskfile.yml` | Task definitions |
|
||||
| `package.json` | npm dependencies and scripts |
|
||||
| `.markdownlint.json` | Markdown linting rules |
|
||||
| `.htmlvalidate.json` | HTML validation rules |
|
||||
| `.htmltest.yml` | Link checker config |
|
||||
|
||||
### Build Output
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `public/` | Generated static site |
|
||||
| `resources/_gen/` | Generated resources (Hugo) |
|
||||
| `data/build_info.json` | Build metadata (git commit, version) |
|
||||
|
||||
## Markdown Frontmatter
|
||||
|
||||
### Standard Page
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Page Title"
|
||||
linkTitle: "Short Title"
|
||||
weight: 10
|
||||
description: >
|
||||
Brief description for SEO and navigation.
|
||||
---
|
||||
```
|
||||
|
||||
### Blog Post
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Post Title"
|
||||
date: 2025-01-15
|
||||
author: "Your Name"
|
||||
description: >
|
||||
Post summary.
|
||||
---
|
||||
```
|
||||
|
||||
## Embedding Architecture Diagrams
|
||||
|
||||
### Basic Embed
|
||||
|
||||
```markdown
|
||||
{{< likec4-view view="view-name" project="project-name" >}}
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
- `view` (required) - The view ID from your LikeC4 model
|
||||
- `project` (optional, default: "architecture") - The LikeC4 project name
|
||||
- `title` (optional, default: "Architecture View: {view}") - Custom header text above the diagram
|
||||
|
||||
### Examples
|
||||
|
||||
```markdown
|
||||
{{< likec4-view view="overview" project="documentation-platform" >}}
|
||||
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}
|
||||
{{< likec4-view view="cicdPipeline" project="documentation-platform" >}}
|
||||
{{< likec4-view view="otc-faas" project="architecture" title="OTC FaaS Deployment" >}}
|
||||
```
|
||||
|
||||
## LikeC4 Commands
|
||||
|
||||
### Regenerate Webcomponents
|
||||
|
||||
After modifying `.c4` files:
|
||||
|
||||
```bash
|
||||
task likec4:generate
|
||||
```
|
||||
|
||||
This regenerates both:
|
||||
|
||||
- `static/js/likec4-webcomponent.js` (EDP architecture)
|
||||
- `static/js/likec4-doc-webcomponent.js` (Documentation platform)
|
||||
|
||||
### Start Development Server
|
||||
|
||||
```bash
|
||||
cd resources/doc-likec4 # or resources/edp-likec4
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
Opens LikeC4 IDE at `http://localhost:5173`
|
||||
|
||||
### Export Diagrams
|
||||
|
||||
```bash
|
||||
cd resources/doc-likec4
|
||||
npx likec4 export png -o ./images .
|
||||
```
|
||||
|
||||
## Git Workflow
|
||||
|
||||
### Feature Branch
|
||||
|
||||
```bash
|
||||
# Create feature branch
|
||||
git checkout -b feature/your-feature
|
||||
|
||||
# Make changes and test
|
||||
task serve
|
||||
task test:quick
|
||||
|
||||
# Commit
|
||||
git add .
|
||||
git commit -m "Description of changes"
|
||||
|
||||
# Push
|
||||
git push origin feature/your-feature
|
||||
|
||||
# Create pull request on GitHub
|
||||
```
|
||||
|
||||
### Update from Main
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout feature/your-feature
|
||||
git rebase main
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port 1313 in use
|
||||
|
||||
```bash
|
||||
lsof -ti:1313 | xargs kill -9
|
||||
```
|
||||
|
||||
### Build errors
|
||||
|
||||
```bash
|
||||
task clean
|
||||
task build:dev
|
||||
```
|
||||
|
||||
### Missing dependencies
|
||||
|
||||
```bash
|
||||
task deps:install
|
||||
```
|
||||
|
||||
### Hugo module issues
|
||||
|
||||
```bash
|
||||
hugo mod clean
|
||||
hugo mod get -u
|
||||
hugo mod tidy
|
||||
```
|
||||
|
||||
### LikeC4 language server
|
||||
|
||||
In VS Code: `Ctrl+Shift+P` → "LikeC4: restart language server"
|
||||
|
||||
## URLs
|
||||
|
||||
### Local Development
|
||||
|
||||
- **Documentation:** <http://localhost:1313>
|
||||
- **LikeC4 IDE:** <http://localhost:5173> (when running `npm start` in likec4 folder)
|
||||
|
||||
### Production
|
||||
|
||||
Check `edgeconnectdeployment.yaml` for deployment URL or run:
|
||||
|
||||
```bash
|
||||
kubectl get service edpdoc -n <namespace>
|
||||
```
|
||||
|
||||
## Quick Checks Before Committing
|
||||
|
||||
1. ✅ `task test:quick` passes
|
||||
2. ✅ Preview looks correct in browser
|
||||
3. ✅ No broken links (visual check)
|
||||
4. ✅ Architecture diagrams render
|
||||
5. ✅ Frontmatter is correct
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Hugo docs:** <https://gohugo.io/documentation/>
|
||||
- **Docsy theme:** <https://www.docsy.dev/docs/>
|
||||
- **LikeC4:** <https://likec4.dev/>
|
||||
- **Task:** <https://taskfile.dev/>
|
||||
|
||||
## View Documentation Architecture
|
||||
|
||||
To understand how this documentation platform works:
|
||||
|
||||
→ Start here: [Documentation About Documentation](../)
|
||||
|
|
@ -1,229 +0,0 @@
|
|||
---
|
||||
title: "Testing"
|
||||
linkTitle: "Testing"
|
||||
weight: 30
|
||||
description: >
|
||||
Quality assurance processes for documentation.
|
||||
---
|
||||
|
||||
## Testing Philosophy
|
||||
|
||||
Quality documentation requires testing. Our testing process validates:
|
||||
|
||||
- **Build integrity** - Hugo can generate the site
|
||||
- **Content quality** - Markdown follows best practices
|
||||
- **HTML validity** - Generated HTML is well-formed
|
||||
- **Link integrity** - No broken internal or external links
|
||||
|
||||
## Testing Capabilities
|
||||
|
||||
{{< likec4-view view="testingCapabilities" project="documentation-platform" >}}
|
||||
|
||||
## Local Testing
|
||||
|
||||
Before committing changes, run tests locally:
|
||||
|
||||
### Quick Tests
|
||||
|
||||
For rapid feedback during development:
|
||||
|
||||
```bash
|
||||
task test:quick
|
||||
```
|
||||
|
||||
This runs:
|
||||
|
||||
- `task test:build` - Hugo build validation
|
||||
- `task test:markdown` - Markdown linting
|
||||
|
||||
### Full Test Suite
|
||||
|
||||
Before creating a pull request:
|
||||
|
||||
```bash
|
||||
task test
|
||||
```
|
||||
|
||||
This runs all tests including:
|
||||
|
||||
- `task test:build` - Build validation
|
||||
- `task test:markdown` - Markdown linting
|
||||
- `task test:html` - HTML validation
|
||||
- `task test:links` - Link checking
|
||||
|
||||
## Individual Tests
|
||||
|
||||
You can run individual tests:
|
||||
|
||||
### Build Test
|
||||
|
||||
Validates that Hugo can build the site:
|
||||
|
||||
```bash
|
||||
task test:build
|
||||
```
|
||||
|
||||
This runs: `hugo --gc --minify --logLevel info`
|
||||
|
||||
**What it checks:**
|
||||
|
||||
- Hugo configuration is valid
|
||||
- Content files have correct frontmatter
|
||||
- Templates render without errors
|
||||
- No circular dependencies in content structure
|
||||
|
||||
### Markdown Lint
|
||||
|
||||
Checks Markdown syntax and style:
|
||||
|
||||
```bash
|
||||
task test:markdown
|
||||
```
|
||||
|
||||
This uses `markdownlint` with custom rules in `.markdownlint.json`.
|
||||
|
||||
**What it checks:**
|
||||
|
||||
- Consistent heading hierarchy
|
||||
- Proper list formatting
|
||||
- Code blocks have language tags
|
||||
- No trailing whitespace
|
||||
- Consistent line length (where applicable)
|
||||
|
||||
**Common issues:**
|
||||
|
||||
- Missing blank lines around code blocks
|
||||
- Inconsistent list markers
|
||||
- Heading levels skipped
|
||||
|
||||
### HTML Validation
|
||||
|
||||
Validates generated HTML:
|
||||
|
||||
```bash
|
||||
task test:html
|
||||
```
|
||||
|
||||
This uses `htmlvalidate` with rules in `.htmlvalidate.json`.
|
||||
|
||||
**What it checks:**
|
||||
|
||||
- Well-formed HTML5
|
||||
- Proper nesting of elements
|
||||
- Valid attributes
|
||||
- Accessible markup
|
||||
|
||||
### Link Checking
|
||||
|
||||
Verifies all links are valid:
|
||||
|
||||
```bash
|
||||
task test:links
|
||||
```
|
||||
|
||||
This uses `htmltest` configured in `.htmltest.yml`.
|
||||
|
||||
**What it checks:**
|
||||
|
||||
- Internal links point to existing pages
|
||||
- External links are reachable
|
||||
- Anchor links target existing elements
|
||||
- No redirects (301/302)
|
||||
|
||||
**Note:** This test can be slow for large sites with many external links.
|
||||
|
||||
## CI Testing
|
||||
|
||||
All tests run automatically on:
|
||||
|
||||
- **Push to `main`** - Full test suite
|
||||
- **Pull requests** - Full test suite
|
||||
|
||||
View the GitHub Actions workflow: `.github/workflows/test.yml`
|
||||
|
||||
### CI Test Results
|
||||
|
||||
If tests fail in CI:
|
||||
|
||||
1. Check the GitHub Actions logs
|
||||
2. Look for specific test failures
|
||||
3. Run the same test locally: `task test:<name>`
|
||||
4. Fix the issue
|
||||
5. Commit and push
|
||||
|
||||
### Artifacts
|
||||
|
||||
CI uploads test artifacts:
|
||||
|
||||
- `htmltest-report/` - Link checking results
|
||||
|
||||
Download these from the GitHub Actions run to investigate failures.
|
||||
|
||||
## Test Configuration Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `.markdownlint.json` | Markdown linting rules |
|
||||
| `.htmlvalidate.json` | HTML validation rules |
|
||||
| `.htmltest.yml` | Link checker configuration |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Test early, test often** - Run `task test:quick` frequently
|
||||
2. **Fix issues immediately** - Don't accumulate technical debt
|
||||
3. **Understand failures** - Read error messages carefully
|
||||
4. **Update tests** - If rules change, update config files
|
||||
5. **Document exceptions** - If you need to ignore a rule, document why
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Markdown: MD031 - Blank lines around fences
|
||||
|
||||
**Problem:** Missing blank line before/after code block
|
||||
|
||||
**Solution:** Add blank lines:
|
||||
|
||||
```markdown
|
||||
Some text
|
||||
|
||||
```bash
|
||||
command here
|
||||
```
|
||||
|
||||
More text
|
||||
```
|
||||
|
||||
### Markdown: MD032 - Blank lines around lists
|
||||
|
||||
**Problem:** Missing blank line before/after list
|
||||
|
||||
**Solution:** Add blank lines:
|
||||
|
||||
```markdown
|
||||
Text before
|
||||
|
||||
- List item 1
|
||||
- List item 2
|
||||
|
||||
Text after
|
||||
```
|
||||
|
||||
### HTML: Invalid nesting
|
||||
|
||||
**Problem:** Elements improperly nested
|
||||
|
||||
**Solution:** Check template files and shortcodes
|
||||
|
||||
### Link Check: 404 Not Found
|
||||
|
||||
**Problem:** Link points to non-existent page
|
||||
|
||||
**Solution:**
|
||||
|
||||
- Fix the link
|
||||
- Create the missing page
|
||||
- Remove the link if no longer relevant
|
||||
|
||||
## Next Steps
|
||||
|
||||
Learn about the automated [CI/CD pipeline](../cicd/).
|
||||
57
content/en/docs/getting-started/_index.md
Normal file
57
content/en/docs/getting-started/_index.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
title: "Getting Started"
|
||||
linkTitle: "Getting Started"
|
||||
weight: 3
|
||||
description: >
|
||||
Quick start guides and onboarding information for the Edge Developer Platform.
|
||||
---
|
||||
|
||||
## Welcome to EDP
|
||||
|
||||
This section helps you get started with the Edge Developer Platform, whether you're a developer building applications or a platform engineer managing infrastructure.
|
||||
|
||||
## Quick Start for Developers
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* Access to EDP instance
|
||||
* Git client installed
|
||||
* kubectl configured (for Kubernetes access)
|
||||
* Basic knowledge of containers and CI/CD
|
||||
|
||||
### Your First Application
|
||||
|
||||
1. **Access the Platform**: Log in to Backstage portal
|
||||
2. **Clone Repository**: Get your application repository from Forgejo/GitLab
|
||||
3. **Configure Pipeline**: Set up CI/CD in Woodpecker or ArgoCD
|
||||
4. **Deploy**: Push code and watch automated deployment
|
||||
|
||||
### Next Steps
|
||||
|
||||
* Explore available components and services
|
||||
* Review platform documentation and best practices
|
||||
* Join the developer community
|
||||
|
||||
## Quick Start for Platform Engineers
|
||||
|
||||
### Platform Access
|
||||
|
||||
* Kubernetes cluster access
|
||||
* Infrastructure management tools
|
||||
* Monitoring and observability dashboards
|
||||
|
||||
### Key Resources
|
||||
|
||||
* Platform architecture documentation
|
||||
* Operational runbooks
|
||||
* Troubleshooting guides
|
||||
|
||||
## Documentation Template
|
||||
|
||||
When creating "Getting Started" content for a component:
|
||||
|
||||
1. **Prerequisites**: What users need before starting
|
||||
2. **Step-by-Step Guide**: Clear, numbered instructions
|
||||
3. **Verification**: How to confirm success
|
||||
4. **Common Issues**: FAQ and troubleshooting
|
||||
5. **Next Steps**: Links to deeper documentation
|
||||
67
content/en/docs/governance/_index.md
Normal file
67
content/en/docs/governance/_index.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
title: "Governance"
|
||||
linkTitle: "Governance"
|
||||
weight: 5
|
||||
description: >
|
||||
Project history, architecture decisions, compliance, and audit information.
|
||||
---
|
||||
|
||||
## Governance Overview
|
||||
|
||||
This section provides information for auditors, governance teams, and stakeholders who need to understand the project's decision-making process, history, and compliance.
|
||||
|
||||
## Architecture Decision Records (ADRs)
|
||||
|
||||
Documentation of significant architectural decisions made during the project, including context, options considered, and rationale.
|
||||
|
||||
## Project History
|
||||
|
||||
### Development Process
|
||||
|
||||
The EDP was developed using collaborative approaches including mob programming and iterative development with regular user feedback.
|
||||
|
||||
### Project Phases
|
||||
|
||||
* Research & Design
|
||||
* Proof of Concept
|
||||
* Friendly User Phase
|
||||
* Production Rollout
|
||||
|
||||
### Deliverables Mapping
|
||||
|
||||
Mapping to IPCEI-CIS deliverables and project milestones.
|
||||
|
||||
## Compliance & Audit
|
||||
|
||||
### Technology Choices
|
||||
|
||||
Documentation of technology evaluation and selection process for key components (e.g., VictoriaMetrics, GARM, Terraform, ArgoCD).
|
||||
|
||||
### Security Controls
|
||||
|
||||
Overview of implemented security controls and compliance measures.
|
||||
|
||||
### Ticket References
|
||||
|
||||
Cross-references to Jira tickets, epics, and project tracking for audit trails.
|
||||
|
||||
## Community & External Relations
|
||||
|
||||
### Open Source Contributions
|
||||
|
||||
Contributions to the Forgejo community and other open-source projects.
|
||||
|
||||
### External Stakeholders
|
||||
|
||||
User experience research and feedback integration.
|
||||
|
||||
## Documentation Template
|
||||
|
||||
When creating governance documentation:
|
||||
|
||||
1. **Context**: Background and situation
|
||||
2. **Decision/Event**: What was decided or what happened
|
||||
3. **Rationale**: Why this decision was made
|
||||
4. **Alternatives**: Other options considered
|
||||
5. **Consequences**: Impact and outcomes
|
||||
6. **References**: Links to tickets, discussions, external resources
|
||||
60
content/en/docs/operations/_index.md
Normal file
60
content/en/docs/operations/_index.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: "Operations"
|
||||
linkTitle: "Operations"
|
||||
weight: 4
|
||||
description: >
|
||||
Operational guides for deploying, monitoring, and maintaining the Edge Developer Platform.
|
||||
---
|
||||
|
||||
## Operations Overview
|
||||
|
||||
This section covers operational aspects of the Edge Developer Platform including deployment, monitoring, troubleshooting, and maintenance.
|
||||
|
||||
## Deployment
|
||||
|
||||
### Platform Deployment
|
||||
|
||||
Instructions for deploying EDP components to your infrastructure.
|
||||
|
||||
### Application Deployment
|
||||
|
||||
Guides for deploying applications to the platform using available deployment methods.
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
### Metrics
|
||||
|
||||
Access and interpret platform and application metrics using VictoriaMetrics, Prometheus, and Grafana.
|
||||
|
||||
### Logging
|
||||
|
||||
Log aggregation and analysis for troubleshooting and audit purposes.
|
||||
|
||||
### Alerting
|
||||
|
||||
Configure alerts for critical platform events and application issues.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues and their solutions for platform operations.
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updates & Upgrades
|
||||
|
||||
Procedures for updating platform components and maintaining system health.
|
||||
|
||||
### Backup & Recovery
|
||||
|
||||
Data backup strategies and disaster recovery procedures.
|
||||
|
||||
## Documentation Template
|
||||
|
||||
When creating operational documentation:
|
||||
|
||||
1. **Purpose**: What this operation achieves
|
||||
2. **Prerequisites**: Required access, tools, and knowledge
|
||||
3. **Procedure**: Step-by-step instructions with commands
|
||||
4. **Verification**: How to confirm successful completion
|
||||
5. **Rollback**: How to revert if needed
|
||||
6. **Troubleshooting**: Common issues and solutions
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
title: "eDF Documentation Overview"
|
||||
description: "Comprehensive guide for users and auditors to understand and use the eDF."
|
||||
---
|
||||
|
||||
# Meta
|
||||
|
||||
## Guidelines
|
||||
|
||||
1. for users/developers/engineers we describe our output / outcome as product
|
||||
* it is usable
|
||||
* there are links / lists to repos
|
||||
2. we have and describe a 'product-structure-tree'
|
||||
3. for auditors / governance we have a list / cross reference to Jira tickets
|
||||
* R&D ?,
|
||||
* mappen auf die projektphasen, wie erstellt ein team eine plattform?
|
||||
* stw. mobbing, mob programming
|
||||
* mapping auf deliverables von IPCEI-CIS ???, bzw. mapping auf epics?
|
||||
* projekthistorie, projektdynamic, teilprojekt von eDF , teilprojekt-abhängigkiet zB 'Platform'
|
||||
* friendly user phase
|
||||
* forgejo community, OSS, PR handling
|
||||
* externe stakeholder, user experience, think ahead integration
|
||||
* technolgien, technologie-schwerpunkte, cutting-edge research
|
||||
* design/specification und bewertung von lösungsentürfen (zB VictoriaMetrics, GARM, terraform, argoCD, ...)
|
||||
* CI/CD, golden paths (anm.: ist in grobkonzept, deployment von apps von developern fehlt)
|
||||
|
||||
# Introduction
|
||||
- Purpose of the eDF
|
||||
- Target audience (developers, engineers, auditors)
|
||||
- High-level product structure overview
|
||||
- High-level architecture overview
|
||||
|
||||
# eDF Components Overview
|
||||
- List of all major components
|
||||
- Vertical and horizontal layers explained
|
||||
- Component maturity/status (fully integrated, partial, experimental)
|
||||
|
||||
# Getting Started
|
||||
- Quickstart guide for developers
|
||||
- Onboarding steps for eDF engineers
|
||||
- Prerequisites and environment setup
|
||||
|
||||
# Component Details
|
||||
For each component:
|
||||
- Description and purpose
|
||||
- Repository link
|
||||
- README summary
|
||||
- Architecture diagrams (link to Miro/Lucid)
|
||||
- Usage instructions
|
||||
- Integration points
|
||||
|
||||
# Development Experience
|
||||
- How to contribute
|
||||
- Local development workflow
|
||||
- CI/CD pipelines
|
||||
- Testing and validation
|
||||
|
||||
# Operational Experience
|
||||
- Deployment guides
|
||||
- Monitoring and observability
|
||||
- Troubleshooting
|
||||
|
||||
# Audit & Compliance
|
||||
- Overview of implemented controls
|
||||
- Ticket references (Jira, changelogs)
|
||||
- Documentation of decisions and reviews
|
||||
- Evidence of value and coverage
|
||||
|
||||
# FAQ & Support
|
||||
- Common issues and solutions
|
||||
- Contact points for help
|
||||
|
||||
# Appendix
|
||||
- Glossary
|
||||
- References to external resources
|
||||
48
content/en/docs/platform-overview/_index.md
Normal file
48
content/en/docs/platform-overview/_index.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: "Platform Overview"
|
||||
linkTitle: "Platform Overview"
|
||||
weight: 1
|
||||
description: >
|
||||
High-level overview of the Edge Developer Platform (EDP), its purpose, and product structure.
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
The Edge Developer Platform (EDP) is a comprehensive DevOps platform designed to enable developers to build, deploy, and operate cloud-native applications at the edge. It provides an integrated suite of tools and services covering the entire software development lifecycle.
|
||||
|
||||
## Target Audience
|
||||
|
||||
* **Developers**: Build and deploy applications using standardized workflows
|
||||
* **Platform Engineers**: Operate and maintain the platform infrastructure
|
||||
* **DevOps Teams**: Implement CI/CD pipelines and automation
|
||||
* **Auditors**: Verify platform capabilities and compliance
|
||||
|
||||
## Product Structure
|
||||
|
||||
EDP consists of multiple integrated components organized in layers:
|
||||
|
||||
### Core Platform Services
|
||||
|
||||
The foundation layer provides essential platform capabilities including source code management, CI/CD, and container orchestration.
|
||||
|
||||
### Developer Experience
|
||||
|
||||
Tools and services that developers interact with directly to build, test, and deploy applications.
|
||||
|
||||
### Infrastructure & Operations
|
||||
|
||||
Infrastructure automation, observability, and operational tooling for platform management.
|
||||
|
||||
## Platform Maturity
|
||||
|
||||
Components in EDP have different maturity levels:
|
||||
|
||||
* **Production**: Fully integrated and supported for production use
|
||||
* **Beta**: Available for testing with potential changes
|
||||
* **Experimental**: Early stage, subject to significant changes
|
||||
|
||||
## Getting Started
|
||||
|
||||
For quick start guides and onboarding information, see the [Getting Started](../getting-started/) section.
|
||||
|
||||
For detailed component information, explore the [Components](../components/) section.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
---
|
||||
title: "Documentation (v1 - Legacy)"
|
||||
linkTitle: "v1 (Legacy)"
|
||||
weight: 100
|
||||
description: >
|
||||
Legacy documentation - archived version of the original content.
|
||||
---
|
||||
|
||||
{{% alert title="Note" color="warning" %}}
|
||||
This is the legacy documentation (v1). For the latest version, please visit the [current documentation](/docs/).
|
||||
{{% /alert %}}
|
||||
|
||||
This section contains the original documentation that is being migrated to a new structure.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
---
|
||||
title: 'Code: Software and Workloads'
|
||||
linktitle: Code
|
||||
weight: 1
|
||||
description: 'The center of everything else, the reason, driver and center of all being: Running Code'
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: Engineers
|
||||
weight: 2
|
||||
description: 'Our clients: People creating code and bringing it to life - and their habits and contexts'
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -1,61 +0,0 @@
|
|||
---
|
||||
title: Use Cases
|
||||
weight: 2
|
||||
description: The golden paths in the engineers and product development domain
|
||||
---
|
||||
|
||||
## Rationale
|
||||
|
||||
The challenge of IPCEI-CIS Developer Framework is to provide value for DTAG customers, and more specifically: for Developers of DTAG customers.
|
||||
|
||||
That's why we need verifications - or test use cases - for the Developer Framework to develop.
|
||||
|
||||
|
||||
(source: https://tag-app-delivery.cncf.io/whitepapers/platforms/)
|
||||
|
||||
## Golden Paths as Use Cases
|
||||
|
||||
* https://platformengineering.org/blog/how-to-pave-golden-paths-that-actually-go-somewhere
|
||||
* https://thenewstack.io/using-an-internal-developer-portal-for-golden-paths/
|
||||
* https://nl.devoteam.com/expert-view/building-golden-paths-with-internal-developer-platforms/
|
||||
* https://www.redhat.com/en/blog/designing-golden-paths
|
||||
|
||||
## List of Use Cases
|
||||
|
||||
Here we have a collection of possible usage scenarios.
|
||||
|
||||
### Socksshop
|
||||
|
||||
Deploy and develop the famous socks shops:
|
||||
|
||||
* https://medium.com/@wadecharley703/socks-shop-microservices-application-deployment-on-the-cloud-cd1017cce1c0
|
||||
|
||||
* See also mkdev fork: https://github.com/mkdev-me/microservices-demo
|
||||
|
||||
### Humanitec Demos
|
||||
|
||||
* https://github.com/poc-template-org/node-js-sample
|
||||
|
||||
### Github Examples
|
||||
|
||||
* https://github.com/kezoo/nestjs-reactjs-graphql-typescript-boilerplate-example
|
||||
|
||||
### Telemetry Use Case with respect to the Fibonacci workload
|
||||
|
||||
The Fibonacci App on the cluster can be accessed on the path https://cnoe.localtest.me/fibonacci.
|
||||
It can be called for example by using the URL https://cnoe.localtest.me/fibonacci?number=5000000.
|
||||
|
||||
The resulting ressource spike can be observed one the Grafana dashboard "Kubernetes / Compute Resources / Cluster".
|
||||
The resulting visualization should look similar like this:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## When and how to use the developer framework?
|
||||
|
||||
### e.g. an example
|
||||
|
||||
.... taken from https://cloud.google.com/blog/products/application-development/common-myths-about-platform-engineering?hl=en
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 154 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 944 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 160 KiB |
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
title: (Digital) Platforms
|
||||
linktitle: Platforms
|
||||
weight: 4
|
||||
description: Platforming is the discipline to provide full sophisticated golden paths to the engineers. It's the next level of DevOps.
|
||||
---
|
||||
|
||||
## Surveys
|
||||
|
||||
* [10-best-internal-developer-platforms-to-consider-in-2023/](https://www.qovery.com/blog/10-best-internal-developer-platforms-to-consider-in-2023/)
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 128 KiB |
|
|
@ -1,15 +0,0 @@
|
|||
---
|
||||
title: "Platform Components"
|
||||
weight: 3
|
||||
description: What in terms of components or building blocks is needed in a platform?
|
||||
---
|
||||
|
||||
> This page is in work. Right now we have in the index a collection of links describing and listing typical components and building blocks of platforms. Also we have a growing number of subsections regarding special types of components.
|
||||
|
||||
See also:
|
||||
|
||||
* https://thenewstack.io/build-an-open-source-kubernetes-gitops-platform-part-1/
|
||||
* https://thenewstack.io/build-an-open-source-kubernetes-gitops-platform-part-2/
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
+++
|
||||
archetype = "sub-chapter"
|
||||
title = "CI/CD Pipeline"
|
||||
weight = 1
|
||||
[params]
|
||||
author = 'florian.fuerstenberg@t-systems.com'
|
||||
date = '2024-10-08'
|
||||
+++
|
||||
|
||||
This document describes the concept of pipelining in the context of the Edge Developer Framework.
|
||||
|
||||
## Overview
|
||||
|
||||
In order to provide a composable pipeline as part of the Edge Developer Framework (EDF), we have defined a set of concepts that can be used to create pipelines for different usage scenarios. These concepts are:
|
||||
|
||||
**Pipeline Contexts** define the context in which a pipeline execution is run. Typically, a context corresponds to a specific step within the software development lifecycle, such as building and testing code, deploying and testing code in staging environments, or releasing code. Contexts define which components are used, in which order, and the environment in which they are executed.
|
||||
|
||||
**Components** are the building blocks, which are used in the pipeline. They define specific steps that are executed in a pipeline such as compiling code, running tests, or deploying an application.
|
||||
|
||||
|
||||
|
||||
## Pipeline Contexts
|
||||
|
||||
We provide 4 Pipeline Contexts that can be used to create pipelines for different usage scenarios. The contexts can be described as the golden path, which is fully configurable and extenable by the users.
|
||||
|
||||
Pipeline runs with a given context can be triggered by different actions. For example, a pipeline run with the `Continuous Integration` context can be triggered by a commit to a repository, while a pipeline run with the `Continuous Delivery` context could be triggered by merging a pull request to a specific branch.
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
This context is focused on running tests and checks on every commit to a repository. It is used to ensure that the codebase is always in a working state and that new changes do not break existing functionality. Tests within this context are typically fast and lightweight, and are used to catch simple errors such as syntax errors, typos, and basic logic errors. Static vulnerability and compliance checks can also be performed in this context.
|
||||
|
||||
### Continuous Delivery
|
||||
|
||||
This context is focused on deploying code to a (ephermal) staging environment after its static checks have been performed. It is used to ensure that the codebase is always deployable and that new changes can be easily reviewed by stakeholders. Tests within this context are typically more comprehensive than those in the Continuous Integration context, and handle more complex scenarios such as integration tests and end-to-end tests. Additionally, live security and compliance checks can be performed in this context.
|
||||
|
||||
### Continuous Deployment
|
||||
|
||||
This context is focused on deploying code to a production environment and/or publishing artefacts after static checks have been performed.
|
||||
|
||||
### Chore
|
||||
|
||||
This context focuses on measures that need to be carried out regularly (e.g. security or compliance scans). They are used to ensure the robustness, security and efficiency of software projects. They enable teams to maintain high standards of quality and reliability while minimizing risks and allowing developers to focus on more critical and creative aspects of development, increasing overall productivity and satisfaction.
|
||||
|
||||
## Components
|
||||
|
||||
Components are the composable and self-contained building blocks for the contexts described above. The aim is to cover most (common) use cases for application teams and make them particularly easy to use by following our golden paths. This way, application teams only have to include and configure the functionalities they actually need. An additional benefit is that this allows for easy extensibility. If a desired functionality has not been implemented as a component, application teams can simply add their own.
|
||||
|
||||
Components must be as small as possible and follow the same concepts of software development and deployment as any other software product. In particular, they must have the following characteristics:
|
||||
|
||||
* designed for a single task
|
||||
* provide a clear and intuitive output
|
||||
* easy to compose
|
||||
* easily customizable or interchangeable
|
||||
* automatically testable
|
||||
|
||||
In the EDF components are divided into different categories. Each category contains components that perform similar actions. For example, the `build` category contains components that compile code, while the `deploy` category contains components that automate the management of the artefacts created in a production-like system.
|
||||
|
||||
> **Note:** Components are comparable to interfaces in programming. Each component defines a certain behaviour, but the actual implementation of these actions depends on the specific codebase and environment.
|
||||
>
|
||||
> For example, the `build` component defines the action of compiling code, but the actual build process depends on the programming language and build tools used in the project. The `vulnerability scanning` component will likely execute different tools and interact with different APIs depending on the context in which it is executed.
|
||||
|
||||
### Build
|
||||
|
||||
Build components are used to compile code. They can be used to compile code written in different programming languages, and can be used to compile code for different platforms.
|
||||
|
||||
### Code Test
|
||||
|
||||
These components define tests that are run on the codebase. They are used to ensure that the codebase is always in a working state and that new changes do not break existing functionality. Tests within this category are typically fast and lightweight, and are used to catch simple errors such as syntax errors, typos, and basic logic errors. Tests must be executable in isolation, and do not require external dependencies such as databases or network connections.
|
||||
|
||||
### Application Test
|
||||
|
||||
Application tests are tests, which run the code in a real execution environment, and provide external dependencies. These tests are typically more comprehensive than those in the `Code Test` category, and handle more complex scenarios such as integration tests and end-to-end tests.
|
||||
|
||||
### Deploy
|
||||
|
||||
Deploy components are used to deploy code to different environments, but can also be used to publish artifacts. They are typically used in the `Continuous Delivery` and `Continuous Deployment` contexts.
|
||||
|
||||
### Release
|
||||
|
||||
Release components are used to create releases of the codebase. They can be used to create tags in the repository, create release notes, or perform other tasks related to releasing code. They are typically used in the `Continuous Deployment` context.
|
||||
|
||||
### Repo House Keeping
|
||||
|
||||
Repo house keeping components are used to manage the repository. They can be used to clean up old branches, update the repository's README file, or perform other maintenance tasks. They can also be used to handle issues, such as automatically closing stale issues.
|
||||
|
||||
### Dependency Management
|
||||
|
||||
Dependency management is used to automate the process of managing dependencies in a codebase. It can be used to create pull requests with updated dependencies, or to automatically update dependencies in a codebase.
|
||||
|
||||
### Security and Compliance
|
||||
|
||||
Security and compliance components are used to ensure that the codebase meets security and compliance requirements. They can be used to scan the codebase for vulnerabilities, check for compliance with coding standards, or perform other security and compliance checks. Depending on the context, different tools can be used to accomplish scanning. In the `Continuous Integration` context, static code analysis can be used to scan the codebase for vulnerabilities, while in the `Continuous Delivery` context, live security and compliance checks can be performed.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 732 KiB |
|
|
@ -1,11 +0,0 @@
|
|||
|
||||
|
||||
# Gitops changes the definition of 'Delivery' or 'Deployment'
|
||||
|
||||
We have Gitops these days .... so there is a desired state of an environment in a repo and a reconciling mechanism done by Gitops to enforce this state on the environemnt.
|
||||
|
||||
There is no continuous whatever step inbetween ... Gitops is just 'overwriting' (to avoid saying 'delivering' or 'deploying') the environment with the new state.
|
||||
|
||||
This means whatever quality ensuring steps have to take part before 'overwriting' have to be defined as state changer in the repos, not in the environments.
|
||||
|
||||
Conclusio: I think we only have three contexts, or let's say we don't have the contect 'continuous delivery'
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
title: "Developer Portals"
|
||||
weight: 2
|
||||
description: Developer portals are one part of the UI for developers to access platforms. The general idea is that the UI parts should be enough for a developer to th their work.
|
||||
---
|
||||
|
||||
> This page is in work. Right now we have in the index a collection of links describing developer portals.
|
||||
|
||||
|
||||
* Backstage (siehe auch https://nl.devoteam.com/expert-view/project-unox/)
|
||||
* [Port](https://www.getport.io/)
|
||||
* Cortex
|
||||
* Humanitec
|
||||
* [OpsLevel](https://docs.opslevel.com/docs/introducing-opslevel#what-is-opslevel)
|
||||
* https://www.configure8.io/
|
||||
* ... tbc ...
|
||||
|
||||
### Port's Comparison vs. Backstage
|
||||
|
||||
https://www.getport.io/compare/backstage-vs-port
|
||||
|
||||
### Cortex's Comparison vs. Backstage, Port, OpsLevel
|
||||
|
||||
* https://www.cortex.io/compare
|
||||
|
||||
### Service Catalogue
|
||||
|
||||
* https://humanitec.com/blog/service-catalogs-and-internal-developer-platforms
|
||||
* https://dzone.com/articles/the-differences-between-a-service-catalog-internal
|
||||
|
||||
## Links
|
||||
|
||||
* [port-vs-backstage-choosing-your-internal-developer-portal](https://medium.com/@vaibhavgupta0702/port-vs-backstage-choosing-your-internal-developer-portal-71c6a6acd979)
|
||||
* [idp-vs-self-service-portal-a-platform-engineering-showdown](https://thenewstack.io/idp-vs-self-service-portal-a-platform-engineering-showdown)
|
||||
* [portals-vs-platform-orchestrator](https://humanitec.com/portals-vs-platform-orchestrator)
|
||||
* [internal-developer-portal-vs-internal-developer-platform](https://www.cortex.io/post/internal-developer-portal-vs-internal-developer-platform)
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
---
|
||||
title: Platform Orchestrator
|
||||
weight: 3
|
||||
description: "The new kid on the block since 2023 ist 'Platform Orchestrating': Do the the magic declaratively cloud natively automated."
|
||||
---
|
||||
|
||||
'Platform Orchestration' is first mentionned by [Thoughtworks in Sept 2023](https://www.thoughtworks.com/en-de/radar/techniques/platform-orchestration)
|
||||
|
||||
## Links
|
||||
|
||||
* [portals-vs-platform-orchestrator](https://humanitec.com/portals-vs-platform-orchestrator)
|
||||
* [kratix.io](https://www.kratix.io/)
|
||||
* https://internaldeveloperplatform.org/platform-orchestrators/
|
||||
* [backstack.dev](https://backstack.dev/blog/)
|
||||
|
||||
### CNOE
|
||||
|
||||
* cnoe.io
|
||||
|
||||
#### Resources
|
||||
|
||||
* [CNOE IDPBuilder](https://cnoe.io/docs/reference-implementation/installations/idpbuilder)
|
||||
* https://github.com/csantanapr/cnoe-examples/tree/main
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
title: List of references
|
||||
weight: 10
|
||||
linktitle: References
|
||||
description: An currently uncurated list of references with respect to typical platform building components
|
||||
---
|
||||
|
||||
## CNCF
|
||||
|
||||
> [Here are capability domains to consider when building platforms for cloud-native computing](https://tag-app-delivery.cncf.io/whitepapers/platforms/#capabilities-of-platforms):
|
||||
|
||||
* Web portals for observing and provisioning products and capabilities
|
||||
* APIs (and CLIs) for automatically provisioning products and capabilities
|
||||
* “Golden path” templates and docs enabling optimal use of capabilities in products
|
||||
* Automation for building and testing services and products
|
||||
* Automation for delivering and verifying services and products
|
||||
* Development environments such as hosted IDEs and remote connection tools
|
||||
* Observability for services and products using instrumentation and dashboards, including observation of functionality, performance and costs
|
||||
* Infrastructure services including compute runtimes, programmable networks, and block and volume storage
|
||||
* Data services including databases, caches, and object stores
|
||||
* Messaging and event services including brokers, queues, and event fabrics
|
||||
* Identity and secret management services such as service and user identity and authorization, certificate and key issuance, and static secret storage
|
||||
* Security services including static analysis of code and artifacts, runtime analysis, and policy enforcement
|
||||
* Artifact storage including storage of container image and language-specific packages, custom binaries and libraries, and source code
|
||||
|
||||
## IDP
|
||||
|
||||
> [An Internal Developer Platform (IDP) should be built to cover 5 Core Components:](https://internaldeveloperplatform.org/core-components/)
|
||||
|
||||
| Core Component | Short Description |
|
||||
| ---- | --- |
|
||||
| Application Configuration Management | Manage application configuration in a dynamic, scalable and reliable way. |
|
||||
| Infrastructure Orchestration | Orchestrate your infrastructure in a dynamic and intelligent way depending on the context. |
|
||||
| Environment Management | Enable developers to create new and fully provisioned environments whenever needed. |
|
||||
| Deployment Management | Implement a delivery pipeline for Continuous Delivery or even Continuous Deployment (CD). |
|
||||
| Role-Based Access Control | Manage who can do what in a scalable way. |
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 554 KiB |
|
|
@ -1,73 +0,0 @@
|
|||
---
|
||||
title: Platform Engineering
|
||||
weight: 1
|
||||
description: Theory and general blue prints of the platform engineering discipline
|
||||
---
|
||||
|
||||
|
||||
## Rationale
|
||||
|
||||
IPCEI-CIS Developer Framework is part of a cloud native technology stack. To design the capabilities and architecture of the Developer Framework we need to define the surounding context and internal building blocks, both aligned with cutting edge cloud native methodologies and research results.
|
||||
|
||||
In CNCF the discipline of building stacks to enhance the developer experience is called 'Platform Engineering'
|
||||
|
||||
## CNCF Platforms White Paper
|
||||
|
||||
[CNCF first asks](https://tag-app-delivery.cncf.io/whitepapers/platforms/) why we need platform engineering:
|
||||
|
||||
> The desire to refocus delivery teams on their core focus and reduce duplication of effort across the organisation has motivated enterprises to implement platforms for cloud-native computing. By investing in platforms, enterprises can:
|
||||
>
|
||||
> * Reduce the cognitive load on product teams and thereby accelerate product development and delivery
|
||||
> * Improve reliability and resiliency of products relying on platform capabilities by dedicating experts to configure and manage them
|
||||
> * Accelerate product development and delivery by reusing and sharing platform tools and knowledge across many teams in an enterprise
|
||||
> * Reduce risk of security, regulatory and functional issues in products and services by governing platform capabilities and the users, tools and processes surrounding them
|
||||
> * Enable cost-effective and productive use of services from public clouds and other managed offerings by enabling delegation of implementations to those providers while maintaining control over user experience
|
||||
|
||||
## `platformengineering.org`'s Definition of Platform Engineering
|
||||
|
||||
> [Platform engineering is the discipline](https://platformengineering.org/blog/what-is-platform-engineering) of designing and building toolchains and workflows that enable self-service capabilities for software engineering organizations in the cloud-native era. Platform engineers provide an integrated product most often referred to as an “Internal Developer Platform” covering the operational necessities of the entire lifecycle of an application.
|
||||
|
||||
## Reference Architecture aka 'Even more wording': Internal Developer Platform vs. Developer Portal vs. Platform
|
||||
|
||||
https://humanitec.com/blog/wtf-internal-developer-platform-vs-internal-developer-portal-vs-paas
|
||||
|
||||
|
||||
|
||||
## Platform Engineering as running a restaurant
|
||||
|
||||
* https://technologyconversations.com/2024/04/29/how-platform-engineering-compares-to-running-a-restaurant/
|
||||
|
||||
|
||||
|
||||
## Internal Developer Platform
|
||||
|
||||
> In IPCEI-CIS right now (July 2024) we are primarily interested in understanding how IDPs are built as one option to implement an IDP is to build it ourselves.
|
||||
|
||||
The outcome of the Platform Engineering discipline is - created by the platform engineering team - a so called 'Internal Developer Platform'.
|
||||
|
||||
One of the first sites focusing on this discipline was [internaldeveloperplatform.org](https://internaldeveloperplatform.org/)
|
||||
|
||||
* [The golden path](https://engineering.atspotify.com/2020/08/how-we-use-golden-paths-to-solve-fragmentation-in-our-software-ecosystem/)
|
||||
|
||||
## Examples of existing IDPs
|
||||
|
||||
The amount of available IDPs as product is rapidly growing.
|
||||
|
||||
[TODO] LIST OF IDPs
|
||||
|
||||
* [internaldeveloperplatform.org - 'Ecosystem'](https://internaldeveloperplatform.org/)
|
||||
* Typical market overview: https://medium.com/@rphilogene/10-best-internal-developer-portals-to-consider-in-2023-c780fbf8ab12
|
||||
* Another one: https://www.qovery.com/blog/10-best-internal-developer-platforms-to-consider-in-2023/
|
||||
* Just found as another example: [platformplane](https://www.platformplane.com/)
|
||||
|
||||
## Additional links
|
||||
|
||||
* [how-to-fail-at-platform-engineering](https://www.cncf.io/blog/2024/03/08/how-to-fail-at-platform-engineering/)
|
||||
* [8-real-world-reasons-to-adopt-platform-engineering](https://thenewstack.io/8-real-world-reasons-to-adopt-platform-engineering/)
|
||||
* [7-core-elements-of-an-internal-developer-platform](https://thenewstack.io/7-core-elements-of-an-internal-developer-platform/)
|
||||
* [internal-developer-platform-vs-internal-developer-portal](https://www.getport.io/blog/internal-developer-platform-vs-internal-developer-portal)
|
||||
|
||||
## Platform 'Initiatives' aka Use Cases
|
||||
|
||||
Cortex is [talking about Use Cases (aka Initiatives):](https://www.youtube.com/watch?v=LrEC-fkBbQo) (or https://www.brighttalk.com/webcast/20257/601901)
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 51 KiB |
|
|
@ -1,37 +0,0 @@
|
|||
+++
|
||||
archetype = "sub-chapter"
|
||||
title = "Reference Architecture"
|
||||
weight = 1
|
||||
[params]
|
||||
author = 'stephan.lo@telekom.de'
|
||||
date = '2024-07-30'
|
||||
+++
|
||||
|
||||
## [The Structure of a Successful Internal Developer Platform](https://platformengineering.org/blog/create-your-own-platform-engineering-reference-architectures)
|
||||
|
||||
In a platform reference architecture there are five main planes that make up an IDP:
|
||||
|
||||
1. Developer Control Plane – this is the primary configuration layer and interaction point for the platform users. Components include Workload specifications such as Score and a portal for developers to interact with.
|
||||
2. Integration and Delivery Plane – this plane is about building and storing the image, creating app and infra configs, and deploying the final state. It usually contains a CI pipeline, an image registry, a Platform Orchestrator, and the CD system.
|
||||
3. Resource Plane – this is where the actual infrastructure exists including clusters, databases, storage or DNS services.
|
||||
4, Monitoring and Logging Plane – provides real-time metrics and logs for apps and infrastructure.
|
||||
5. Security Plane – manages secrets and identity to protect sensitive information, e.g., storing, managing, and security retrieving API keys and credentials/secrets.
|
||||
|
||||
|
||||
|
||||
(source: https://humanitec.com/blog/wtf-internal-developer-platform-vs-internal-developer-portal-vs-paas)
|
||||
|
||||
|
||||
## Humanitec
|
||||
|
||||
https://github.com/humanitec-architecture
|
||||
|
||||
https://humanitec.com/reference-architectures
|
||||
|
||||
|
||||
## Create a reference architecture
|
||||
|
||||
[Create your own platform reference architecture](https://platformengineering.org/blog/create-your-own-platform-engineering-reference-architectures)
|
||||
|
||||
[Reference arch slide deck](https://docs.google.com/presentation/d/1yAf_FSjiA0bAFukgu5p1DRMvvGGE1fF4KhvZbb7gn2I/edit?pli=1#slide=id.g1ef66f3349b_3_3)
|
||||
|
||||
|
|
@ -1,158 +0,0 @@
|
|||
---
|
||||
title: CNOE
|
||||
weight: 4
|
||||
---
|
||||
|
||||
|
||||
* https://cnoe.io/docs/intro
|
||||
|
||||
> The goal for the CNOE framework is to bring together a cohort of enterprises operating at the same scale so that they can navigate their operational technology decisions together, de-risk their tooling bets, coordinate contribution, and offer guidance to large enterprises on which CNCF technologies to use together to achieve the best cloud efficiencies.
|
||||
|
||||
### Aussprache
|
||||
|
||||
* Englisch Kuh.noo,
|
||||
* also 'Kanu' im Deutschen
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
|
||||
## Run the CNOEs reference implementation
|
||||
|
||||
See https://cnoe.io/docs/reference-implementation/integrations/reference-impl:
|
||||
|
||||
```bash
|
||||
# in a local terminal with docker and kind
|
||||
idpbuilder create --use-path-routing --log-level debug --package-dir https://github.com/cnoe-io/stacks//ref-implementation
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
```bash
|
||||
time=2024-08-05T14:48:33.348+02:00 level=INFO msg="Creating kind cluster" logger=setup
|
||||
time=2024-08-05T14:48:33.371+02:00 level=INFO msg="Runtime detected" logger=setup provider=docker
|
||||
########################### Our kind config ############################
|
||||
# Kind kubernetes release images https://github.com/kubernetes-sigs/kind/releases
|
||||
kind: Cluster
|
||||
apiVersion: kind.x-k8s.io/v1alpha4
|
||||
nodes:
|
||||
- role: control-plane
|
||||
image: "kindest/node:v1.29.2"
|
||||
kubeadmConfigPatches:
|
||||
- |
|
||||
kind: InitConfiguration
|
||||
nodeRegistration:
|
||||
kubeletExtraArgs:
|
||||
node-labels: "ingress-ready=true"
|
||||
extraPortMappings:
|
||||
- containerPort: 443
|
||||
hostPort: 8443
|
||||
protocol: TCP
|
||||
|
||||
containerdConfigPatches:
|
||||
- |-
|
||||
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."gitea.cnoe.localtest.me:8443"]
|
||||
endpoint = ["https://gitea.cnoe.localtest.me"]
|
||||
[plugins."io.containerd.grpc.v1.cri".registry.configs."gitea.cnoe.localtest.me".tls]
|
||||
insecure_skip_verify = true
|
||||
|
||||
######################### config end ############################
|
||||
time=2024-08-05T14:48:33.394+02:00 level=INFO msg="Creating kind cluster" logger=setup cluster=localdev
|
||||
time=2024-08-05T14:48:53.680+02:00 level=INFO msg="Done creating cluster" logger=setup cluster=localdev
|
||||
time=2024-08-05T14:48:53.905+02:00 level=DEBUG+3 msg="Getting Kube config" logger=setup
|
||||
time=2024-08-05T14:48:53.908+02:00 level=DEBUG+3 msg="Getting Kube client" logger=setup
|
||||
time=2024-08-05T14:48:53.908+02:00 level=INFO msg="Adding CRDs to the cluster" logger=setup
|
||||
time=2024-08-05T14:48:53.948+02:00 level=DEBUG+3 msg="crd not yet established, waiting." "crd name"=custompackages.idpbuilder.cnoe.io
|
||||
time=2024-08-05T14:48:53.954+02:00 level=DEBUG+3 msg="crd not yet established, waiting." "crd name"=custompackages.idpbuilder.cnoe.io
|
||||
time=2024-08-05T14:48:53.957+02:00 level=DEBUG+3 msg="crd not yet established, waiting." "crd name"=custompackages.idpbuilder.cnoe.io
|
||||
time=2024-08-05T14:48:53.981+02:00 level=DEBUG+3 msg="crd not yet established, waiting." "crd name"=gitrepositories.idpbuilder.cnoe.io
|
||||
time=2024-08-05T14:48:53.985+02:00 level=DEBUG+3 msg="crd not yet established, waiting." "crd name"=gitrepositories.idpbuilder.cnoe.io
|
||||
time=2024-08-05T14:48:54.734+02:00 level=DEBUG+3 msg="Creating controller manager" logger=setup
|
||||
time=2024-08-05T14:48:54.737+02:00 level=DEBUG+3 msg="Created temp directory for cloning repositories" logger=setup dir=/tmp/idpbuilder-localdev-2865684949
|
||||
time=2024-08-05T14:48:54.737+02:00 level=INFO msg="Setting up CoreDNS" logger=setup
|
||||
time=2024-08-05T14:48:54.798+02:00 level=INFO msg="Setting up TLS certificate" logger=setup
|
||||
time=2024-08-05T14:48:54.811+02:00 level=DEBUG+3 msg="Creating/getting certificate" logger=setup host=cnoe.localtest.me sans="[cnoe.localtest.me *.cnoe.localtest.me]"
|
||||
time=2024-08-05T14:48:54.825+02:00 level=DEBUG+3 msg="Creating secret for certificate" logger=setup host=cnoe.localtest.me
|
||||
time=2024-08-05T14:48:54.832+02:00 level=DEBUG+3 msg="Running controllers" logger=setup
|
||||
time=2024-08-05T14:48:54.833+02:00 level=DEBUG+3 msg="starting manager"
|
||||
time=2024-08-05T14:48:54.833+02:00 level=INFO msg="Creating localbuild resource" logger=setup
|
||||
time=2024-08-05T14:48:54.834+02:00 level=INFO msg="Starting EventSource" controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage source="kind source: *v1alpha1.CustomPackage"
|
||||
time=2024-08-05T14:48:54.834+02:00 level=INFO msg="Starting EventSource" controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository source="kind source: *v1alpha1.GitRepository"
|
||||
time=2024-08-05T14:48:54.834+02:00 level=INFO msg="Starting Controller" controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
time=2024-08-05T14:48:54.834+02:00 level=INFO msg="Starting Controller" controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
time=2024-08-05T14:48:54.834+02:00 level=INFO msg="Starting EventSource" controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild source="kind source: *v1alpha1.Localbuild"
|
||||
time=2024-08-05T14:48:54.834+02:00 level=INFO msg="Starting Controller" controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
time=2024-08-05T14:48:54.937+02:00 level=INFO msg="Starting workers" controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository "worker count"=1
|
||||
time=2024-08-05T14:48:54.937+02:00 level=INFO msg="Starting workers" controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage "worker count"=1
|
||||
time=2024-08-05T14:48:54.937+02:00 level=INFO msg="Starting workers" controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild "worker count"=1
|
||||
time=2024-08-05T14:48:56.863+02:00 level=DEBUG+3 msg=Reconciling controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild Localbuild.name=localdev namespace="" name=localdev reconcileID=cc0e5b9d-4952-4fd1-9d62-6d9821f180be resource=/localdev
|
||||
time=2024-08-05T14:48:56.863+02:00 level=DEBUG+3 msg="Create or update namespace" controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild Localbuild.name=localdev namespace="" name=localdev reconcileID=cc0e5b9d-4952-4fd1-9d62-6d9821f180be resource="&Namespace{ObjectMeta:{idpbuilder-localdev 0 0001-01-01 00:00:00 +0000 UTC <nil> <nil> map[] map[] [] [] []},Spec:NamespaceSpec{Finalizers:[],},Status:NamespaceStatus{Phase:,Conditions:[]NamespaceCondition{},},}"
|
||||
time=2024-08-05T14:48:56.983+02:00 level=DEBUG+3 msg="installing core packages" controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild Localbuild.name=localdev namespace="" name=localdev reconcileID=cc0e5b9d-4952-4fd1-9d62-6d9821f180be
|
||||
time=2024-08-05T14:
|
||||
|
||||
...
|
||||
|
||||
time=2024-08-05T14:51:04.166+02:00 level=INFO msg="Stopping and waiting for webhooks"
|
||||
time=2024-08-05T14:51:04.166+02:00 level=INFO msg="Stopping and waiting for HTTP servers"
|
||||
time=2024-08-05T14:51:04.166+02:00 level=INFO msg="Wait completed, proceeding to shutdown the manager"
|
||||
|
||||
########################### Finished Creating IDP Successfully! ############################
|
||||
|
||||
|
||||
Can Access ArgoCD at https://cnoe.localtest.me:8443/argocd
|
||||
Username: admin
|
||||
Password can be retrieved by running: idpbuilder get secrets -p argocd
|
||||
```
|
||||
|
||||
## Outcome
|
||||
|
||||
Nach ca. 10 minuten sind alle applications ausgerollt (am längsten dauert Backstage):
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~$ kubectl get applications -A
|
||||
NAMESPACE NAME SYNC STATUS HEALTH STATUS
|
||||
argocd argo-workflows Synced Healthy
|
||||
argocd argocd Synced Healthy
|
||||
argocd backstage Synced Healthy
|
||||
argocd included-backstage-templates Synced Healthy
|
||||
argocd coredns Synced Healthy
|
||||
argocd external-secrets Synced Healthy
|
||||
argocd gitea Synced Healthy
|
||||
argocd keycloak Synced Healthy
|
||||
argocd metric-server Synced Healthy
|
||||
argocd nginx Synced Healthy
|
||||
argocd spark-operator Synced Healthy
|
||||
stl@ubuntu-vpn:~$ idpbuilder get secrets
|
||||
---------------------------
|
||||
Name: argocd-initial-admin-secret
|
||||
Namespace: argocd
|
||||
Data:
|
||||
password : sPMdWiy0y0jhhveW
|
||||
username : admin
|
||||
---------------------------
|
||||
Name: gitea-credential
|
||||
Namespace: gitea
|
||||
Data:
|
||||
password : |iJ+8gG,(Jj?cc*G>%(i'OA7@(9ya3xTNLB{9k'G
|
||||
username : giteaAdmin
|
||||
---------------------------
|
||||
Name: keycloak-config
|
||||
Namespace: keycloak
|
||||
Data:
|
||||
KC_DB_PASSWORD : ES-rOE6MXs09r+fAdXJOvaZJ5I-+nZ+hj7zF
|
||||
KC_DB_USERNAME : keycloak
|
||||
KEYCLOAK_ADMIN_PASSWORD : BBeMUUK1CdmhKWxZxDDa1c5A+/Z-dE/7UD4/
|
||||
POSTGRES_DB : keycloak
|
||||
POSTGRES_PASSWORD : ES-rOE6MXs09r+fAdXJOvaZJ5I-+nZ+hj7zF
|
||||
POSTGRES_USER : keycloak
|
||||
USER_PASSWORD : RwCHPvPVMu+fQM4L6W/q-Wq79MMP+3CN-Jeo
|
||||
```
|
||||
|
||||
### login to backstage
|
||||
|
||||
login geht mit den Creds, siehe oben:
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 113 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 364 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 208 KiB |
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: Humanitec
|
||||
weight: 4
|
||||
---
|
||||
|
||||
|
||||
tbd
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
---
|
||||
title: Platform Orchestrators
|
||||
linktitle: Orchestrators
|
||||
weight: 5
|
||||
description: Platform automation is the next level of platforming
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: Concepts
|
||||
weight: 1
|
||||
description: The underlying platforming concepts of the Edge Developer Framework (EDF) solution, i.e. the problem domain
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -1,269 +0,0 @@
|
|||
|
||||
|
||||
# Ideen
|
||||
|
||||
* Kanban
|
||||
* product review sessions
|
||||
|
||||
# ChatGPT
|
||||
|
||||
## Fehlendes Backlog
|
||||
|
||||
> welche agilen vorgehensmodelle bzw. best practices gibt es in der software-entwicklung, wenn das product backlog noch nicht da ist. es gibt zwar eine produktvision und auch schon einen PoC, aber das Produkt ist sowohl technisch als auch nutzenseitig immer nocht nicht planbar in user stories. daher ist SCRUM nicht machbar. das team ist ca. 8 personen groß, und wir überlgen, einen meilenstein in den nächsten 8 wochen einfach durch tägliches 'PDCA' zu erstellen: ein morgendliches planning, dann in subgruppen ein erforschen, dann im Plenum wieder C (Check) zusammenführen/integrieren, und ein abschliessendes 'A' als Ergebnissicherung, Versionierierung, Dokumentation. Was hälst du von diesem Vorgehen, bzw. welches Risiken und Verbesserungsvorschläge hast du? Oder gibt es ein Standard-Vorgehen hierfür?
|
||||
|
||||
Dein beschriebenes Szenario – Vision und PoC vorhanden, aber kein ausformuliertes Product Backlog – ist typisch für eine frühe **Explorations- oder Inceptionsphase** in der Produktentwicklung. In dieser Phase ist klassisches **Scrum** tatsächlich oft zu starr, weil es eine gewisse Klarheit über Features und Stories voraussetzt. Das von euch überlegte Vorgehen klingt nach einer sehr pragmatischen und iterativen Methode, die im Kern gut zu den **Lean-Startup-Prinzipien** oder **Design Thinking + Agile Engineering** passt.
|
||||
|
||||
## Bewertung eures PDCA-basierten Vorgehens
|
||||
|
||||
**Positiv:**
|
||||
* **Täglicher PDCA-Zyklus** (Plan-Do-Check-Act) sorgt für schnelle Feedbackschleifen.
|
||||
* **Morgendliches Planning** und **Check-Meeting im Plenum** fördern Transparenz und Selbstorganisation.
|
||||
* **Subgruppen-Erkundung** erlaubt parallele Experimente.
|
||||
* **Abschließendes "A"** zur Ergebnissicherung ist essenziell, sonst bleibt es bei "busy work".
|
||||
|
||||
**Risiken:**
|
||||
|
||||
1. **Fehlende Langfriststruktur:** Ohne grobe übergreifende Richtung (z. B. Meilensteinplan, Zielbild) kann es leicht in ziellosem Explorieren enden.
|
||||
2. **Uneinheitlicher Erkenntnisgewinn:** Subgruppen könnten redundant oder inkompatibel arbeiten, wenn kein gemeinsames Verständnis besteht.
|
||||
3. **Dokumentation als „Nachsorge“:** Wenn die Doku erst am Ende passiert, droht Wissensverlust – lieber „Living Docs“ in Echtzeit pflegen.
|
||||
4. **Stakeholder-Abkopplung:** Ohne explizite Reviews oder Demo-Rituale kann Feedback von außen fehlen.
|
||||
|
||||
## Verbesserungsvorschläge
|
||||
|
||||
1. **Exploration Backlog oder Hypothesenboard:** Auch ohne klassisches Product Backlog könnt ihr mit einem **Experiment-/Hypothesenboard** (à la Lean Startup) arbeiten. Zum Beispiel:
|
||||
* Hypothese: „Feature X wird den Use Case Y verbessern.“
|
||||
* Experiment: „Prototyp bauen und testen mit Nutzergruppe Z.“
|
||||
* Ergebnis & Learnings dokumentieren.
|
||||
|
||||
2. **Wöchentliche Zielsetzungen:** Jeden Montag ein Weekly Planning mit klaren Zielen für die Woche (Outcome-fokussiert, nicht Task-fokussiert).
|
||||
|
||||
3. **Integration mit Dual Track Agile:** Das Vorgehen ähnelt dem **Dual-Track-Modell**: ein **Discovery-Track** (Erkunden, Validieren, Prototypisieren) läuft parallel zum späteren **Delivery-Track** (Releases, Sprints). Ihr seid noch voll im Discovery-Track.
|
||||
|
||||
4. **Design Studio oder Spike-Zeitfenster:** Strukturiert Zeit für z. B. 2-Tages-Design-Studios oder 1-Tages-Spikes – das erhöht die Qualität der Exploration.
|
||||
|
||||
5. **Review/Share-Session freitags:** Eine fixe wöchentliche Review-/Demo-Session (auch intern) erhöht die Disziplin und hilft beim „Check“-Teil im PDCA.
|
||||
|
||||
## Gängige Standard-Methoden in dieser Phase
|
||||
|
||||
* **Design Thinking** (für Nutzerzentrierte Exploration)
|
||||
* **Lean UX / Lean Startup** (Hypothesengetrieben)
|
||||
* **Dual Track Agile**
|
||||
* **Google Design Sprint (5 Tage)** – extrem hilfreich, wenn es um das Testen von Nutzerideen geht
|
||||
* **Shape Up (Basecamp)** – für nicht-sprintbasiertes Arbeiten mit "Bet" auf 6-Wochen-Projekte
|
||||
|
||||
---
|
||||
|
||||
**Fazit:**
|
||||
Euer PDCA-Zyklus ist ein solider, pragmatischer Einstieg in eine unsichere, vorstrukturierte Produktphase. Mit ein paar Ergänzungen (Exploration Backlog, feste Review-Elemente, Hypothesenstruktur) könnt ihr daraus ein effektives Discovery-Vorgehen machen, das den Übergang zu einem klassischen agilen Framework (z. B. Scrum) vorbereitet.
|
||||
|
||||
Möchtest du eine konkrete Vorlage für ein Exploration Backlog oder Hypothesenboard für euer Team?
|
||||
|
||||
## Architektur vorhanden
|
||||
|
||||
> ok, du findest vor allem Tages-Zyklen zu kurz. Ich möchte noch ergänzen, dass wir eine Architektur haben. Das klingt vielleicht paradox, aber es ist tatsächlich so, dass wir das Software-syewtm bereits designed haben, und die Komponenten auch bereits kennen, aber jetzt vor allem die Wege des automatischen Deployments in eine Cloud und die Konfigurations- und Verwaltungsstrukturen unsrerer Software herausfinden müssen. Das ist da, was sich gerade nicht weiter planen lässt. Kannst du mit diesen Ergänzungen dein Feedbach nochmal schärfen?
|
||||
|
||||
Danke für die Ergänzung – das ändert die Ausgangslage entscheidend und erlaubt eine deutlich präzisere Einordnung.
|
||||
|
||||
### Neue Ausgangslage
|
||||
|
||||
* Ihr **habt eine Architektur**: Die Komponenten und Schnittstellen sind klar.
|
||||
* Es gibt **bereits einen PoC** und eine Produktvision.
|
||||
* Das **Backlog fehlt**, weil ihr gerade die **"nicht-funktionalen" Themen wie Deployment, Cloud-Umgebung, Konfiguration und Betrieb** klärt.
|
||||
* Das System ist **technisch grob fertig designt**, aber die **Operations- und Deployment-Prozesse** sind unklar und werden explorativ entwickelt.
|
||||
|
||||
### Schärferes Feedback
|
||||
|
||||
#### 1. **Tages-PDCA-Zyklen wirken in diesem Kontext zu granular**
|
||||
|
||||
Bei Infrastruktur-, Deployment- oder Konfigurationsfragen entstehen oft tiefe „Spikes“ (z. B. CI/CD-Pipeline aufsetzen, Helm-Chart modellieren, Secrets Handling evaluieren). Diese brauchen oft mehr als einen Tag bis zum „Check“, weil Abhängigkeiten (z. B. Rechte, Cloud-Zugänge, Testumgebungen) entstehen. Ein **2- bis 3-Tages-Rhythmus** mit klaren Zwischenzielen wäre realistischer, ergänzt um:
|
||||
|
||||
* **Daily Standup als Taktgeber**, aber nicht zwangsläufig als vollständiger PDCA-Zyklus.
|
||||
* **Weekly Planning mit Zielvorgaben und Review-Ritualen**, um Fortschritt messbar zu machen.
|
||||
|
||||
#### 2. **Was ihr macht, ist kein Produkt-Delivery, sondern "System Enablement"**
|
||||
|
||||
Ihr steckt im Übergang von Architektur zu einem **Infrastructure as Code + Plattform Enablement Track**. Das bedeutet:
|
||||
* Die „User Stories“ sind keine klassischen Features, sondern z. B.:
|
||||
* „Als Team möchte ich unsere Software mit einem Befehl deployen können.“
|
||||
* „Als Betreiber will ich wissen, wie ich Services konfiguriere.“
|
||||
|
||||
Das spricht für ein **Infrastructure Kanban Board**, keine Sprints.
|
||||
|
||||
#### 3. **Mögliche Vorgehensmodelle / Best Practices**
|
||||
|
||||
| Modell / Methode | Warum es jetzt passt |
|
||||
|------------------------------------------|------------------------------------------------------------------|
|
||||
| **Kanban für technische Tasks** | Flexible Work-in-Progress-Kontrolle, ideal für Exploration. |
|
||||
| **Spikes** (aus XP) | Timeboxed Exploration zu offenen Fragen (z. B. Helm, Secrets). |
|
||||
| **Enabler Epics (SAFe)** | Deployment- und Ops-Fragen formal als "Enabler" fassen. |
|
||||
| **Team Topologies – Platform Team Light**| Ihr agiert gerade wie ein internes Plattform-Team. |
|
||||
| **Weekly DevOps Review** | Alle 5–7 Tage Stand der Automatisierung/Doku/Strukturen. |
|
||||
| **ADRs & Living Docs** | Architectural Decision Records für Deployment-/Ops-Entscheidungen.|
|
||||
|
||||
#### 4. **Konkrete Empfehlungen zur Strukturierung**
|
||||
|
||||
* **Ziele für die 8 Wochen formulieren** als **"Capabilities"**, z. B.:
|
||||
* „Greenfield-Clouddeployment in AWS/GCP über GitHub Actions.“
|
||||
* „Parameterisierbares Helm-Chart mit Doku.“
|
||||
* „Konfigurierbarkeit über ENV vs. Secrets evaluieren.“
|
||||
* Dazu **1–2 Woche cadence**, jede Woche ein Review/Checkpoint.
|
||||
* **Boards mit Task-Kategorien**:
|
||||
* 🧪 Spike
|
||||
* 🛠️ Tooling/Automation
|
||||
* 📦 Infrastruktur/Dienst
|
||||
* 📓 Dokumentation
|
||||
* **Ergebnisse sofort versionieren und dokumentieren**, z. B.:
|
||||
* GitOps Repo-Struktur
|
||||
* ADRs
|
||||
* Beispiel-Deployments
|
||||
|
||||
---
|
||||
|
||||
### Fazit
|
||||
|
||||
Ihr seid im **"technisch operativen Enablement"** eures Systems, nicht im Produkt-Delivery. Das rechtfertigt:
|
||||
* ein **kanban-artiges, flexibles Modell mit timeboxed Reviews**,
|
||||
* tägliche Abstimmungen, aber nicht zwingend tägliche Zyklen,
|
||||
* Fokus auf **Enabler-Ziele statt funktionale Stories**.
|
||||
|
||||
SCRUM ist hier fehl am Platz, aber euer Ansatz ist sehr nahe an einer **modernen DevOps-orientierten Arbeitsweise**, die z. B. von **Platform Engineering Teams** eingesetzt wird.
|
||||
|
||||
Möchtest du ein Beispiel für ein solches Kanban-Board mit passenden Task-Typen und Zielstruktur?
|
||||
|
||||
## Kanban
|
||||
|
||||
> ja, gerne!
|
||||
|
||||
Hier ist ein konkretes Beispiel für ein **Kanban-Board**, das speziell auf eure Situation als „Platform/Enablement“-Team mit einem vorhandenen Architekturbild, aber offenem Deployment- und Betriebsdesign zugeschnitten ist.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Zielstruktur (übergeordnet für 8 Wochen)**
|
||||
|
||||
Diese formuliert ihr am besten als **Capabilities** – Fähigkeiten, die das System nachher haben soll:
|
||||
|
||||
| Capability ID | Zielbeschreibung |
|
||||
|---------------|---------------------------------------------------------------------------------------------|
|
||||
| C1 | Anwendung kann automatisiert in Cloudumgebung X deployed werden (inkl. Secrets Mgmt) |
|
||||
| C2 | Konfiguration des Systems ist externisiert und dokumentiert (ENV, YAML, o. ä.) |
|
||||
| C3 | Monitoring- und Logging-Infrastruktur ist einsatzbereit und dokumentiert |
|
||||
| C4 | Dev- und Test-Umgebungen sind klar getrennt und automatisch provisionierbar |
|
||||
| C5 | Alle Plattformentscheidungen (z. B. Helm vs. Kustomize) sind versioniert und begründet |
|
||||
|
||||
Diese Capabilities bilden **Spalten** oder **Swimlanes** im Board (wenn euer Tool das unterstützt, z. B. GitHub Projects, Jira oder Trello mit Labels).
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ **Kanban-Board-Spalten (klassisch)**
|
||||
|
||||
| Spalte | Zweck |
|
||||
|------------------|-----------------------------------------------------------|
|
||||
| 🔍 Backlog | Ideen, Hypothesen, Tasks – priorisiert nach Capabilities |
|
||||
| 🧪 In Exploration | Aktive Spikes, Proofs, technische Evaluierungen |
|
||||
| 🛠️ In Progress | Umsetzung mit konkretem Ziel |
|
||||
| ✅ Review / Check | Funktionsprüfung, internes Review |
|
||||
| 📦 Done | Abgeschlossen, dokumentiert, ggf. in Repo |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ **Task-Typen (Labels oder Emojis zur Kennzeichnung)**
|
||||
|
||||
| Symbol / Label | Typ | Beispiel |
|
||||
|------------------|-----------------------------|--------------------------------------------------------------------------|
|
||||
| 🧪 Spike | Technische Untersuchung | „Untersuche ArgoCD vs. Flux für GitOps Deployment“ |
|
||||
| 📦 Infra | Infrastruktur | „Provisioniere dev/test/stage in GCP mit Terraform“ |
|
||||
| 🔐 Secrets | Sicherheitsrelevante Aufgabe| „Design für Secret-Handling mit Sealed Secrets“ |
|
||||
| 📓 Docs | Dokumentation | „README für Developer Setup schreiben“ |
|
||||
| 🧰 Tooling | CI/CD, Pipelines, Linter | „GitHub Action für Build & Deploy schreiben“ |
|
||||
| 🔁 Entscheidung | Architekturentscheidung | „ADR: Helm vs. Kustomize für Service Deployment“ |
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Beispielhafte Tasks für Capability „C1 – Deployment automatisieren“
|
||||
|
||||
| Task | Typ | Status |
|
||||
|----------------------------------------------|----------|----------------|
|
||||
| Write GitHub Action for Docker image push | 🧰 Tooling | 🛠️ In Progress |
|
||||
| Evaluate ArgoCD vs. Flux | 🧪 Spike | ✅ Review |
|
||||
| Create Helm Chart for Service A | 📦 Infra | 🔍 Backlog |
|
||||
| Create ADR: Deployment-Toolentscheidung | 🔁 Entscheidung | 🔍 Backlog |
|
||||
| Add deployment doc in Wiki | 📓 Docs | 🔍 Backlog |
|
||||
|
||||
---
|
||||
|
||||
## 📅 Cadence-Empfehlung
|
||||
|
||||
* **Daily Standup (15 min)**: Was läuft, was blockiert? Pull statt Push!
|
||||
* **Weekly Planning (Montag)**: Priorisieren und Backlog-Grooming (welche Capabilities sind diese Woche dran?)
|
||||
* **Weekly Review (Freitag)**: Erkenntnisse, Entscheidungen und Dokumentation präsentieren
|
||||
* Optional: **Retrospektive alle 2 Wochen**, falls das Team Energie hat
|
||||
|
||||
---
|
||||
|
||||
Wenn du magst, kann ich dir ein Beispiel-Board als Markdown-Vorlage oder als CSV-Datei zum Import in Trello, GitHub Projects, Jira etc. machen. Wäre das hilfreich?
|
||||
|
||||
## Living Docs
|
||||
|
||||
> kannst du noch etwas mehr zu 'LivingDocs' sagen?
|
||||
|
||||
Ja, gerne! **"Living Docs"** (bzw. **Living Documentation**) ist ein Konzept aus der agilen Softwareentwicklung und DevOps, das sich auf **aktuelle, direkt aus dem System oder aus dem Arbeitsprozess generierte Dokumentation** bezieht. Ziel ist es, dass die Dokumentation *nicht veraltet*, sondern so eng mit Code und Systemzustand gekoppelt ist, dass sie sich (teilweise) selbst aktualisiert oder sich mit dem Entwicklungsprozess mitbewegt.
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **Was macht "Living Documentation" aus?**
|
||||
|
||||
| Merkmal | Beschreibung |
|
||||
|----------------------------------|------------------------------------------------------------------------------|
|
||||
| 🔄 Automatisch erzeugt oder aktualisiert | Generiert aus Code, Tests, Pipelines, ADRs oder Deployments |
|
||||
| 📌 Versionskontrolliert | Im Git abgelegt, gemeinsam mit dem Code gepflegt |
|
||||
| 🧑💻 Entwicklernah | Entwickelt sich mit dem Code weiter – keine Trennung zwischen "Docs" und Dev |
|
||||
| 📈 Änderbar & nachvollziehbar | Jede Änderung an Code/Doku hat einen Commit & Kontext |
|
||||
| 📚 Mehrwert für alle Beteiligten| Richtet sich an Devs, Ops, PMs oder andere Teams – nicht nur "für später" |
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Typische Formen von Living Docs
|
||||
|
||||
| Typ | Beschreibung & Tools |
|
||||
|----------------------|----------------------------------------------------------------------------------------|
|
||||
| **Architecture Decision Records (ADRs)** | Markdown-Dateien im Repo (z. B. `docs/adr/001-helm-vs-kustomize.md`) |
|
||||
| **Code-Doku aus Source** | Mit Tools wie JSDoc, TypeDoc, Sphinx, Doxygen, etc. |
|
||||
| **API-Doku** | Automatisch aus Code oder OpenAPI (Swagger) generiert |
|
||||
| **Test-Doku (z. B. BDD)** | z. B. Gherkin-Style: `Given/When/Then`-Spezifikationen als Dokumentation |
|
||||
| **Monitoring & Deployment-Status** | z. B. Dashboards mit Infrastructure-Doku (Grafana, Backstage, Argo UI) |
|
||||
| **DevDocs im Repo** | z. B. `README.md`, `CONTRIBUTING.md`, `how-to/`, `docs/`, `adr/` |
|
||||
| **Playbooks / Runbooks** | Schritt-für-Schritt-Anleitungen für Betrieb oder Störungen |
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Best Practices**
|
||||
|
||||
1. **Nutze Markdown + Git:** Einfach, versionierbar, lesbar → ADRs, Runbooks, HowTos.
|
||||
2. **Dokumentiere Entscheidungen bewusst:** Lieber knappe, saubere ADRs als keine Doku.
|
||||
3. **Verknüpfe Doku mit Code / CI/CD:** Beispiel: Build-Tool erzeugt automatisch API-Doku oder ADR-Lint-Checks.
|
||||
4. **Verlinke Logs, Dashboards, Monitoring:** z. B. in einem `system-overview.md`.
|
||||
5. **Behandle Doku wie Code:** Reviewpflichtig, Pull Request basiert, CI-checkbar.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tools & Frameworks
|
||||
|
||||
| Zweck | Tools (Beispiele) |
|
||||
|------------------------|-------------------------------------------------------------------------|
|
||||
| ADRs | [`adr-tools`](https://github.com/npryce/adr-tools), einfaches Markdown |
|
||||
| Markdown-Doku | MkDocs, Docusaurus, GitBook |
|
||||
| API-Doku | Swagger/OpenAPI, Redocly |
|
||||
| Infrastruktur-Doku | Backstage (Spotify), Terraform-docs |
|
||||
| Doku-Automatisierung | GitHub Actions, pre-commit Hooks, CI-Checks |
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Denkweise: Doku = Gespräch in Zeit
|
||||
|
||||
> "Dokumentation ist kein Nachtrag, sondern ein asynchrones Gespräch mit deinem zukünftigen Ich – oder dem nächsten Teammitglied."
|
||||
|
||||
Gerade in eurem Kontext (technisches Enablement, Deployment, Betrieb) ist das **entscheidungsorientierte, leichtgewichtige Festhalten von Kontext** Gold wert. ADRs und `docs/runbooks/`-Verzeichnisse sind ein idealer Startpunkt.
|
||||
|
||||
---
|
||||
|
||||
Möchtest du eine Vorlage für ein ADR oder ein Beispielverzeichnis für eine sinnvolle Living-Docs-Struktur im Repo?
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
title: Project
|
||||
weight: 5
|
||||
description: How we organize work and proceed as team, which decisions we made, what outputs and outcomes we have
|
||||
---
|
||||
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: Bootstrapping Infrastructure
|
||||
weight: 30
|
||||
description: The cluster and the installed applications in the bootstrapping cluster
|
||||
---
|
||||
|
||||
In order to be able to do useful work, we do need a number of applications right away. We're deploying these manually so we have the necessary basis for our work. Once the framework has been developed far enough, we will deploy this infrastructure with the framework itself.
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
---
|
||||
title: Backup of the Bootstrapping Cluster
|
||||
weight: 30
|
||||
description: Backup and Restore of the Contents of the Bootstrapping Cluster
|
||||
---
|
||||
|
||||
## Velero
|
||||
|
||||
We are using [Velero](https://velero.io/) for backup and restore of the deployed applications.
|
||||
|
||||
## Installing Velero Tools
|
||||
|
||||
To manage a Velero install in a cluster, you need to have Velero command line tools installed locally. Please follow the instructions for [Basic Install](https://velero.io/docs/v1.9/basic-install).
|
||||
|
||||
## Setting Up Velero For a Cluster
|
||||
|
||||
Installing and configuring Velero for a cluster can be accomplished with the CLI.
|
||||
|
||||
1. Create a file with the credentials for the S3 compatible bucket that is storing the backups, for example `credentials.ini`.
|
||||
|
||||
```ini
|
||||
[default]
|
||||
aws_access_key_id = "Access Key Value"
|
||||
aws_secret_access_key = "Secret Key Value"
|
||||
```
|
||||
|
||||
2. Install Velero in the cluster
|
||||
|
||||
```
|
||||
velero install \
|
||||
--provider aws \
|
||||
--plugins velero/velero-plugin-for-aws:v1.2.1 \
|
||||
--bucket osc-backup \
|
||||
--secret-file ./credentials.ini \
|
||||
--use-volume-snapshots=false \
|
||||
--use-node-agent=true \
|
||||
--backup-location-config region=minio,s3ForcePathStyle="true",s3Url=https://obs.eu-de.otc.t-systems.com
|
||||
```
|
||||
|
||||
3. Delete `credentials.ini`, it is not needed anymore (a secret has been created in the cluster).
|
||||
4. Create a schedule to back up the relevant resources in the cluster:
|
||||
|
||||
```
|
||||
velero schedule create devfw-bootstrap --schedule="23 */2 * * *" "--include-namespaces=forgejo"
|
||||
```
|
||||
|
||||
## Working with Velero
|
||||
|
||||
You can now use Velero to create backups, restore them, or perform other operations. Please refer to the [Velero Documentation](https://velero.io/docs/main/backup-reference/).
|
||||
|
||||
To list all currently available backups:
|
||||
|
||||
```
|
||||
velero backup get
|
||||
```
|
||||
|
||||
## Setting up a Service Account for Access to the OTC Object Storage Bucket
|
||||
|
||||
We are using the S3-compatible Open Telekom Cloud Object Storage service to make available some storage for the backups. We picked OTC specifically because we're not using it for anything else, so no matter what catastrophy we create in Open Sovereign Cloud, the backups should be safe.
|
||||
|
||||
### Create an Object Storage Service Bucket
|
||||
|
||||
1. Log in to the [OTC Console with the correct tenant](https://auth.otc.t-systems.com/authui/federation/websso?domain_id=81e7dbd7ec9f4b03a58120dfaa61d3db&idp=ADFS_MMS_OTC00000000001000113497&protocol=saml).
|
||||
1. Navigate to [Object Storage Service](https://console.otc.t-systems.com/obs/?agencyId=WEXsFwkkVdGYULIrZT1icF4nmHY1dgX2®ion=eu-de&locale=en-us#/obs/manager/buckets).
|
||||
1. Click Create Bucket in the upper right hand corner. Give your bucket a name. No further configuration should be necessary.
|
||||
|
||||
### Create a Service User to Access the Bucket
|
||||
|
||||
1. Log in to the [OTC Console with the correct tenant](https://auth.otc.t-systems.com/authui/federation/websso?domain_id=81e7dbd7ec9f4b03a58120dfaa61d3db&idp=ADFS_MMS_OTC00000000001000113497&protocol=saml).
|
||||
1. Navigate to [Identity and Access Management](https://console.otc.t-systems.com/iam/?agencyId=WEXsFwkkVdGYULIrZT1icF4nmHY1dgX2®ion=eu-de&locale=en-us#/iam/users).
|
||||
1. Navigate to User Groups, and click Create User Group in the upper right hand corner.
|
||||
1. Enter a suitable name ("OSC Cloud Backup") and click OK.
|
||||
1. In the group list, locate the group just created and click its name.
|
||||
1. Click Authorize to add the necessary roles. Enter "OBS" in the search box to filter for Object Storage roles.
|
||||
1. Select "OBS OperateAccess", if there are two roles, select them both.
|
||||
1. **2024-10-15** Also select the "OBS Administrator" role. It is unclear why the "OBS OperateAccess" role is not sufficient, but without the admin role, the service user will not have write access to the bucket.
|
||||
1. Click Next to save the roles, then click OK to confirm, then click Finish.
|
||||
1. Navigate to Users, and click Create User in the upper right hand corner.
|
||||
1. Give the user a sensible name ("ipcei-cis-devfw-osc-backups").
|
||||
1. Disable Management console access
|
||||
1. Enable Access key, disable Password, disable Login protection.
|
||||
1. Click Next
|
||||
1. Pick the group created earlier.
|
||||
1. Download the access key when prompted.
|
||||
|
||||
The access key is a CSV file with the Access Key and the Secret Key listed in the second line.
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
---
|
||||
title: Introduction
|
||||
weight: 1
|
||||
description: The 5-step storyflow of this Onboarding chapter
|
||||
---
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
This onboarding section is for you when are new to IPCEI-CIS subproject 'Edge Developer Framework (EDF)' and you want to know about
|
||||
|
||||
* its context to 'Platform Engineering'
|
||||
* and why we think it's the stuff we need to care about in the EDF
|
||||
{{% /pageinfo %}}
|
||||
|
||||
|
||||
## Storyline of our current project plan (2024)
|
||||
|
||||
1. We have the ['Edge Developer Framework'](./edgel-developer-framework/)
|
||||
2. We think the solution for EDF is in relation to ['Platforming' (Digital Platforms)](./platforming/)
|
||||
1. The next evolution after DevOps
|
||||
2. Gartner predicts 80% of SWE companies to have platforms in 2026
|
||||
3. Platforms have a history since roundabout 2019
|
||||
4. CNCF has a working group which created capabilities and a maturity model
|
||||
3. Platforms evolve - nowadys there are [Platform Orchestrators](./orchestrators/)
|
||||
1. Humanitec set up a Reference Architecture
|
||||
2. There is this 'Orchestrator' thing - declaratively describe, customize and change platforms!
|
||||
4. Mapping our assumptions to the [CNOE solution](./cnoe/)
|
||||
1. CNOE is a hot candidate to help and fulfill our platform building
|
||||
2. CNOE aims to embrace change and customization!
|
||||
5. [Showtime CNOE](./cnoe-showtime/)
|
||||
|
||||
|
||||
## Please challenge this story!
|
||||
|
||||
Please do not think this story and the underlying assumptions are carved in stone!
|
||||
|
||||
1. Don't miss to further investigate and truely understand [**EDF specification needs**](./edgel-developer-framework/)
|
||||
2. Don't miss to further investigate and truely understand [**Platform capabilities on top of DevOps**](./platforming/)
|
||||
3. Don't miss to further investigate and truely understand [**Platform orchestration**](./orchestrators/)
|
||||
3. Don't miss to further investigate and truely understand [**specific orchestratiing solutions like CNOE**](./cnoe/)
|
||||
|
||||
## Your role as 'Framework Engineer' in the Domain Architecture
|
||||
|
||||
Pls be aware of the the following domain and task structure of our mission:
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
title: Edge Developer Framework
|
||||
weight: 2
|
||||
description: Driving requirements for a platform
|
||||
---
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
The 'Edge Developer Framework' is both the project and the product we are working for. Out of the leading 'Portfolio Document'
|
||||
we derive requirements which are ought to be fulfilled by Platform Engineering.
|
||||
|
||||
**This is our claim!**
|
||||
|
||||
{{% /pageinfo %}}
|
||||
|
||||
## What are the specifications we know from the IPCEI-CIS Project Portfolio document
|
||||
|
||||
> Reference: IPCEI-CIS Project Portfolio
|
||||
> Version 5.9, November 17, 2023
|
||||
|
||||
### DTAG´s IPCEI-CIS Project Portfolio (p.12)
|
||||
|
||||
e. Development of DTAG/TSI Edge Developer Framework
|
||||
|
||||
* Goal: All developed innovations must be accessible to developer communities in a **highly user-friendly and easy way**
|
||||
|
||||
### Development of DTAG/TSI Edge Developer Framework (p.14)
|
||||
|
||||
| capability | major novelties |||
|
||||
| -- | -- | -- | -- |
|
||||
| e.1. Edge Developer full service framework (SDK + day1 +day2 support for edge installations) | Adaptive CI/CD pipelines for heterogeneous edge environments | Decentralized and self healing deployment and management | edge-driven monitoring and analytics |
|
||||
| e.2. Built-in sustainability optimization in Edge developer framework | sustainability optimized edge-aware CI/CD tooling | sustainability-optimized configuration management | sustainability-optimized efficient deployment strategies |
|
||||
| e.3. Sustainable-edge management-optimized user interface for edge developers | sustainability optimized User Interface | Ai-Enabled intelligent experience | AI/ML-based automated user experience testing and optimization |
|
||||
|
||||
### DTAG objectives & contributions (p.27)
|
||||
|
||||
DTAG will also focus on developing an easy-to-use **Edge Developer framework for software
|
||||
developers** to **manage the whole lifecycle of edge applications**, i.e. for **day-0-, day-1- and up to day-2-
|
||||
operations**. With this DTAG will strongly enable the ecosystem building for the entire IPCEI-CIS edge to
|
||||
cloud continuum and ensure openness and accessibility for anyone or any company to make use and
|
||||
further build on the edge to cloud continuum. Providing the use of the tool framework via an open-source approach will further reduce entry barriers and enhance the openness and accessibility for anyone or
|
||||
any organization (see innovations e.).
|
||||
|
||||
### WP Deliverables (p.170)
|
||||
|
||||
e.1 Edge developer full-service framework
|
||||
|
||||
This tool set and related best practices and guidelines will **adapt, enhance and further innovate DevOps principles** and
|
||||
their related, necessary supporting technologies according to the specific requirements and constraints associated with edge or edge cloud development, in order to keep the healthy and balanced innovation path on both sides,
|
||||
the (software) development side and the operations side in the field of DevOps.
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
### What comes next?
|
||||
|
||||
[Next](../platforming/) we'll see how these requirements seem to be fulfilled by platforms!
|
||||
{{% /pageinfo %}}
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
title: Platform Engineering aka Platforming
|
||||
linktitle: Platforming
|
||||
weight: 3
|
||||
description: DevOps is dead - long live next level DevOps in platforms
|
||||
---
|
||||
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
Since 2010 we have DevOps. This brings increasing delivery speed and efficiency at scale.
|
||||
But next we got high 'cognitive loads' for developers and production congestion due to engineering lifecycle complexity.
|
||||
So we need on top of DevOps an instrumentation to ensure and enforce speed, quality, security in modern, cloud native software development. This instrumentation is called 'golden paths' in intenal develoepr platforms (IDP).
|
||||
{{% /pageinfo %}}
|
||||
|
||||
|
||||
## History of Platform Engineering
|
||||
|
||||
Let's start with a look into the history of platform engineering. A good starting point is [Humanitec](https://humanitec.com/), as they nowadays are one of the biggest players (['the market leader in IDPs.'](https://internaldeveloperplatform.org/#how-we-curate-this-site)) in platform engineering.
|
||||
|
||||
They create lots of [beautiful articles and insights](https://humanitec.com/blog), their own [platform products](https://humanitec.com/products/) and [basic concepts for the platform architecture](https://humanitec.com/platform-engineering) (we'll meet this later on!).
|
||||
|
||||
<img src="./humanitec-history.png" width="600" alt="https://platformengineering.org/blog/the-story-of-platform-engineering">
|
||||
|
||||
|
||||
### Further nice reference to the raise of platforms
|
||||
|
||||
* [What we **call** a Platform](https://martinfowler.com/articles/talk-about-platforms.html)
|
||||
* [Platforms and the **cloud native** connection](https://developers.redhat.com/articles/2024/05/06/)what-platform-engineering-and-why-do-we-need-it#why_we_need_platform_engineering
|
||||
* [Platforms and **microservices**](https://orkohunter.net/blog/a-brief-history-of-platform-engineering)
|
||||
* [Platforms in the **product** perspective](https://softwareengineeringdaily.com/2020/02/13/setting-the-stage-for-platform-engineering/)
|
||||
|
||||
|
||||
## Benefit of Platform Engineering, Capabilities
|
||||
|
||||
In [The Evolution of Platform Engineering](https://www.linkedin.com/pulse/evolution-platform-engineering-gaurav-goel) the interconnection inbetween DevOps, Cloud Native, and the Rise of Platform Engineering is nicely presented and summarizes:
|
||||
|
||||
> Platform engineering can be broadly defined as the discipline of designing and building toolchains and workflows that enable self-service capabilities for software engineering organizations
|
||||
|
||||
When looking at these 'capabilities', we have CNCF itself:
|
||||
|
||||
### CNCF Working group / White paper defines layerwed capabilities
|
||||
|
||||
There is a CNCF working group which provides the definition of [Capabilities of platforms](https://tag-app-delivery.cncf.io/whitepapers/platforms/#capabilities-of-platforms) and shows a first idea of the layered architecture of platforms as **service layer for developers** ("product and application teams"):
|
||||
|
||||
<img src="./platforms-def.drawio.png" width="600">
|
||||
|
||||
|
||||
> Important: As Platform engineer also notice the [platform-eng-maturity-model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/)
|
||||
|
||||
### Platform Engineering Team
|
||||
|
||||
Or, in another illustration for the platform as a developer service interface, which also defines the **'Platform Engineering Team'** inbetween:
|
||||
|
||||
<img src="./platform-self-services.webp" width="600" alt="https://medium.com/@bijit211987/what-is-platform-engineering-and-how-it-reduce-cognitive-load-on-developers-ac7805603925">
|
||||
|
||||
## How to set up Platforms
|
||||
|
||||
As we now have evidence about the nescessity of platforms, their capabilities and benefit as self service layer for developers, we want to thin about how to build them.
|
||||
|
||||
First of all some important wording to motivate the important term 'internal developer platfoms' (we will go into this deeper in the next section [with the general architecture](../orchestrators/)), which is clear today, but took years to evolve and [is still some amount if effort to jump in](https://humanitec.com/blog/wtf-internal-developer-platform-vs-internal-developer-portal-vs-paas):
|
||||
|
||||
* Platform: As defined above: A product which serves software engineering teams
|
||||
* Platform Engineering: Creating such a product
|
||||
* Internal Developer Platforms (IDP): A platform for developers :-)
|
||||
* Internal Developer Portal: The entry point of a developer to such an IDP
|
||||
|
||||
### CNCF mapping from capabilities to (CNCF) projects/tools
|
||||
|
||||
[Capabilities of platforms](https://tag-app-delivery.cncf.io/whitepapers/platforms/#capabilities-of-platforms)
|
||||
|
||||
### Ecosystems in InternalDeveloperPlatform
|
||||
|
||||
Build or buy - this is also in pltaform engineering a tweaked discussion, which one of the oldest player answers like this with some oppinioated internal capability structuring:
|
||||
|
||||
[internaldeveloperplatform.org[(https://internaldeveloperplatform.org/platform-tooling/)
|
||||
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
### What comes next?
|
||||
|
||||
[Next](../orchestrators/) we'll see how these concepts got structured!
|
||||
{{% /pageinfo %}}
|
||||
|
||||
## Addendum
|
||||
|
||||
### Digital Platform defintion from [What we **call** a Platform](https://martinfowler.com/articles/talk-about-platforms.html)
|
||||
|
||||
> Words are hard, it seems. ‘Platform’ is just about the most ambiguous term we could use for an approach that is super-important for increasing delivery speed and efficiency at scale. Hence the title of this article, here is what I’ve been talking about most recently.
|
||||
\
|
||||
Definitions for software and hardware platforms abound, generally describing an operating environment upon which applications can execute and which provides reusable capabilities such as file systems and security.
|
||||
\
|
||||
Zooming out, at an organisational level a ‘digital platform’ has similar characteristics - an operating environment which teams can build upon to deliver product features to customers more quickly, supported by reusable capabilities.
|
||||
\
|
||||
A digital platform is a foundation of self-service APIs, tools, services, knowledge and support which are arranged as a compelling internal product. Autonomous delivery teams can make use of the platform to deliver product features at a higher pace, with reduced co-ordination.
|
||||
|
||||
### Myths :-) - What are platforms _not_
|
||||
|
||||
[common-myths-about-platform-engineering](https://cloud.google.com/blog/products/application-development/common-myths-about-platform-engineering?hl=en)
|
||||
|
||||
### Platform Teams
|
||||
|
||||
This is about you :-), the platform engineering team:
|
||||
|
||||
[how-to-build-your-platform-engineering-team](https://platformengineering.org/blog/how-to-build-your-platform-engineering-team)
|
||||
|
||||
#### in comparison: devops vs sre vs platform
|
||||
|
||||
https://www.qovery.com/blog/devops-vs-platform-engineering-is-there-a-difference/
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 904 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 160 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 600 KiB |
|
|
@ -1,55 +0,0 @@
|
|||
---
|
||||
title: Orchestrators
|
||||
weight: 4
|
||||
description: Next level platforming is orchestrating platforms
|
||||
---
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
When defining and setting up platforms next two intrinsic problems arise:
|
||||
|
||||
1. it is not declarative and automated
|
||||
2. it is not or least not easily changable
|
||||
|
||||
Thus the technology of 'Platform Orchestrating' emerged recently, in late 2023.
|
||||
|
||||
{{% /pageinfo %}}
|
||||
|
||||
## Platform reference architecture
|
||||
|
||||
An interesting difference between the CNCF white paper building blocks and them from Internaldeveloperplatforms is the part [**orchestrators**](https://internaldeveloperplatform.org/platform-orchestrators/).
|
||||
|
||||
This is something extremely new since late 2023 - the rise of the automation of platform engineering!
|
||||
|
||||
It was Humanitec creating a definition of platform architecture, as they needed to defien what they are building with their 'orchestrator':
|
||||
|
||||
<img src="./vendor-neutral-idp-final.gif" width="600" alt="https://developer.humanitec.com/introduction/overview/">
|
||||
|
||||
## Declarative Platform Orchestration
|
||||
|
||||
Based on the refence architecture you next can build - or let's say 'orchestrate' - different platform implementations, based on declarative definitions of the platform design.
|
||||
|
||||
https://humanitec.com/reference-architectures
|
||||
|
||||
<img src="./platform-architectures.webp" width="600" alt="https://humanitec.com/blog/aws-azure-and-gcp-open-source-reference-architectures-to-start-your-mvp">
|
||||
|
||||
> Hint: There is a [slides tool provided by McKinsey](https://platformengineering.org/blog/create-your-own-platform-engineering-reference-architectures) to set up your own platform deign based on the reference architecture
|
||||
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
### What comes next?
|
||||
|
||||
[Next](../cnoe/) we'll see how we are going to do platform orchestration with CNOE!
|
||||
{{% /pageinfo %}}
|
||||
|
||||
## Addendum
|
||||
|
||||
## Building blocks from Humanitecs 'state-of-platform-engineering-report-volume-2'
|
||||
|
||||
You remember the [capability mappings from the time before orchestration](../platforming)? Here we have a [similar setup based on Humanitecs platform engineering status ewhite paper](https://humanitec.com/whitepapers/state-of-platform-engineering-report-volume-2):
|
||||
|
||||
<img src="./platform-tooling-humanitec-platform-report-2024.PNG" width="600" alt="https://humanitec.com/whitepapers/state-of-platform-engineering-report-volume-2 Whitepaper_ State of Platform Engineering Report.pdf">
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 723 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 397 KiB |
|
|
@ -1,64 +0,0 @@
|
|||
---
|
||||
title: CNOE
|
||||
weight: 5
|
||||
description: Our top candidate for a platform orchestrator
|
||||
---
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
In late 2023 platform orchestration raised - the discipline of declarativley dinfing, building, orchestarting and reconciling building blocks of (digital) platforms.
|
||||
|
||||
The famost one ist the platform orchestrator from Humanitec. They provide lots of concepts and access, also open sourced tools and schemas. But they do not have open sourced the ocheastartor itself.
|
||||
|
||||
Thus we were looking for open source means for platform orchestrating and found [CNOE](https://cnoe.io).
|
||||
{{% /pageinfo %}}
|
||||
|
||||
## Requirements for an Orchestrator
|
||||
|
||||
When we want to set up a [complete platform](../platforming/platforms-def.drawio.png) we expect to have
|
||||
|
||||
* a **schema** which defines the platform, its ressources and internal behaviour
|
||||
* a **dynamic configuration or templating mechanism** to provide a concrete specification of a platform
|
||||
* a **deployment mechanism** to deploy and reconcile the platform
|
||||
|
||||
This is what [CNOE delivers](https://cnoe.io/docs/intro/approach):
|
||||
|
||||
> For seamless transition into a CNOE-compliant delivery pipeline, CNOE will aim at delivering **"packaging specifications"**, **"templating mechanisms"**, as well as **"deployer technologies"**, an example of which is enabled via the idpBuilder tool we have released. The combination of templates, specifications, and deployers allow for bundling and then unpacking of CNOE recommended tools into **a user's DevOps environment**. This enables teams to share and deliver components that are deemed to be the best tools for the job.
|
||||
|
||||
## CNOE (capabilities) architecture
|
||||
|
||||
### Architecture
|
||||
|
||||
CNOE architecture looks a bit different than the reference architecture from Humanitec, but this just a matter of details and arrangement:
|
||||
|
||||
> Hint: **This has to be further investigated!** This is subject to an Epic.
|
||||
|
||||
<img src="./cnoe-architecture.png" width="600" alt="https://cnoe.io/">
|
||||
|
||||
### Capabilities
|
||||
|
||||
You have a [definition of all the capabilities here](https://cnoe.io/docs/category/technology-capabilities):
|
||||
|
||||
> Hint: **This has to be further investigated!** This is subject to an Epic.
|
||||
|
||||
<img src="./cnoe-capabilities.png" width="600" alt="https://cnoe.io/docs/category/technology-capabilities">
|
||||
|
||||
## Stacks
|
||||
|
||||
CNOE calls the [schema and templating mechnanism 'stacks'](https://github.com/cnoe-io/stacks):
|
||||
|
||||
> Hint: **This has to be further investigated!** This is subject to an Epic.
|
||||
|
||||
There are already some example stacks:
|
||||
|
||||
<img src="./cnoe-stacks.png" width="600">
|
||||
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
### What comes next?
|
||||
|
||||
[Next](../cnoe-showtime/) we'll see how a CNOE stacked Internal Developer Platform is deployed on you local laptop!
|
||||
{{% /pageinfo %}}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 167 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 120 KiB |
|
|
@ -1,582 +0,0 @@
|
|||
---
|
||||
title: CNOE Showtime
|
||||
weight: 6
|
||||
description: CNOE hands on
|
||||
---
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
CNOE is a 'Platform Engineering Framework' (Danger: Our wording!) - it is open source and locally runnable.
|
||||
|
||||
It consists of the orchestrator 'idpbuilder' and both of some predefined building blocks and also some predefined platform configurations.
|
||||
|
||||
{{% /pageinfo %}}
|
||||
|
||||
|
||||
## Orchestrator 'idpbuilder', initial run
|
||||
|
||||
The orchestrator in CNOE is called 'idpbuilder'. It is [locally installable binary](https://cnoe.io/docs/reference-implementation/installations/idpbuilder/quick-start)
|
||||
|
||||
A typipcal first setup ist described here: https://cnoe.io/docs/reference-implementation/technology
|
||||
|
||||
```bash
|
||||
# this is a local linux shell
|
||||
|
||||
# check local installation
|
||||
type idpbuilder
|
||||
idpbuilder is /usr/local/bin/idpbuilder
|
||||
|
||||
# check version
|
||||
idpbuilder version
|
||||
idpbuilder 0.8.0-nightly.20240914 go1.22.7 linux/amd64
|
||||
|
||||
# do some completion and aliasing
|
||||
source <(idpbuilder completion bash)
|
||||
alias ib=idpbuilder
|
||||
complete -F __start_idpbuilder ib
|
||||
|
||||
# check and remove all existing kind clusters
|
||||
kind delete clusters --all
|
||||
kind get clusters
|
||||
# sth. like 'No kind clusters found.'
|
||||
|
||||
# run
|
||||
$ib create --use-path-routing --log-level debug --package-dir https://github.com/cnoe-io/stacks//ref-implementation
|
||||
```
|
||||
|
||||
You get output like
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/ipceicis-developerframework$ idpbuilder create
|
||||
Oct 1 10:09:18 INFO Creating kind cluster logger=setup
|
||||
Oct 1 10:09:18 INFO Runtime detected logger=setup provider=docker
|
||||
########################### Our kind config ############################
|
||||
# Kind kubernetes release images https://github.com/kubernetes-sigs/kind/releases
|
||||
kind: Cluster
|
||||
apiVersion: kind.x-k8s.io/v1alpha4
|
||||
nodes:
|
||||
- role: control-plane
|
||||
image: "kindest/node:v1.30.0"
|
||||
labels:
|
||||
ingress-ready: "true"
|
||||
extraPortMappings:
|
||||
- containerPort: 443
|
||||
hostPort: 8443
|
||||
protocol: TCP
|
||||
|
||||
containerdConfigPatches:
|
||||
- |-
|
||||
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."gitea.cnoe.localtest.me:8443"]
|
||||
endpoint = ["https://gitea.cnoe.localtest.me"]
|
||||
[plugins."io.containerd.grpc.v1.cri".registry.configs."gitea.cnoe.localtest.me".tls]
|
||||
insecure_skip_verify = true
|
||||
|
||||
######################### config end ############################
|
||||
```
|
||||
|
||||
## Show time steps
|
||||
|
||||
> Goto https://cnoe.io/docs/reference-implementation/installations/idpbuilder/usage, and follow the flow
|
||||
|
||||
### Prepare a k8s cluster with kind
|
||||
|
||||
You may have seen: when starting `idpbuilder` without an existing cluster named `localdev` it first creates this cluster by calling `kind`with an internally defined config.
|
||||
|
||||
It's an important feature of idpbuilder that it will set up on an existing cluster `localdev` when called several times in a row e.g. to append new packages to the cluster.
|
||||
|
||||
That's why we here first create the kind cluster `localdev`itself:
|
||||
|
||||
```bash
|
||||
cat << EOF | kind create cluster --name localdev --config=-
|
||||
# Kind kubernetes release images https://github.com/kubernetes-sigs/kind/releases
|
||||
kind: Cluster
|
||||
apiVersion: kind.x-k8s.io/v1alpha4
|
||||
nodes:
|
||||
- role: control-plane
|
||||
image: "kindest/node:v1.30.0"
|
||||
labels:
|
||||
ingress-ready: "true"
|
||||
extraPortMappings:
|
||||
- containerPort: 443
|
||||
hostPort: 8443
|
||||
protocol: TCP
|
||||
|
||||
containerdConfigPatches:
|
||||
- |-
|
||||
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."gitea.cnoe.localtest.me:8443"]
|
||||
endpoint = ["https://gitea.cnoe.localtest.me"]
|
||||
[plugins."io.containerd.grpc.v1.cri".registry.configs."gitea.cnoe.localtest.me".tls]
|
||||
insecure_skip_verify = true
|
||||
```
|
||||
|
||||
```bash
|
||||
# alternatively, if you have the kind config as file:
|
||||
kind create cluster --name localdev --config kind-config.yaml
|
||||
```
|
||||
|
||||
#### Output
|
||||
|
||||
A typical raw kind setup kubernetes cluster would look like this with respect to running pods:
|
||||
|
||||
> be sure all pods are in status 'running'
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/idpbuilder$ k get pods -A
|
||||
NAMESPACE NAME READY STATUS RESTARTS AGE
|
||||
kube-system coredns-76f75df574-lb7jz 1/1 Running 0 15s
|
||||
kube-system coredns-76f75df574-zm2wp 1/1 Running 0 15s
|
||||
kube-system etcd-localdev-control-plane 1/1 Running 0 27s
|
||||
kube-system kindnet-8qhd5 1/1 Running 0 13s
|
||||
kube-system kindnet-r4d6n 1/1 Running 0 15s
|
||||
kube-system kube-apiserver-localdev-control-plane 1/1 Running 0 27s
|
||||
kube-system kube-controller-manager-localdev-control-plane 1/1 Running 0 27s
|
||||
kube-system kube-proxy-vrh64 1/1 Running 0 15s
|
||||
kube-system kube-proxy-w8ks9 1/1 Running 0 13s
|
||||
kube-system kube-scheduler-localdev-control-plane 1/1 Running 0 27s
|
||||
local-path-storage local-path-provisioner-6f8956fb48-6fvt2 1/1 Running 0 15s
|
||||
```
|
||||
|
||||
### First run: Start with core applications, 'core package'
|
||||
|
||||
Now we run idpbuilder the first time:
|
||||
|
||||
```
|
||||
# now idpbuilder reuses the already existing cluster
|
||||
# pls apply '--use-path-routing' otherwise as we discovered currently the service resolving inside the cluster won't work
|
||||
ib create --use-path-routing
|
||||
```
|
||||
|
||||
#### Output
|
||||
|
||||
##### idpbuilder log
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/idpbuilder$ ib create --use-path-routing
|
||||
Oct 1 10:32:50 INFO Creating kind cluster logger=setup
|
||||
Oct 1 10:32:50 INFO Runtime detected logger=setup provider=docker
|
||||
Oct 1 10:32:50 INFO Cluster already exists logger=setup cluster=localdev
|
||||
Oct 1 10:32:50 INFO Adding CRDs to the cluster logger=setup
|
||||
Oct 1 10:32:51 INFO Setting up CoreDNS logger=setup
|
||||
Oct 1 10:32:51 INFO Setting up TLS certificate logger=setup
|
||||
Oct 1 10:32:51 INFO Creating localbuild resource logger=setup
|
||||
Oct 1 10:32:51 INFO Starting EventSource controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository source=kind source: *v1alpha1.GitRepository
|
||||
Oct 1 10:32:51 INFO Starting Controller controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
Oct 1 10:32:51 INFO Starting EventSource controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild source=kind source: *v1alpha1.Localbuild
|
||||
Oct 1 10:32:51 INFO Starting Controller controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
Oct 1 10:32:51 INFO Starting EventSource controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage source=kind source: *v1alpha1.CustomPackage
|
||||
Oct 1 10:32:51 INFO Starting Controller controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
Oct 1 10:32:51 INFO Starting workers controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild worker count=1
|
||||
Oct 1 10:32:51 INFO Starting workers controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage worker count=1
|
||||
Oct 1 10:32:51 INFO Starting workers controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository worker count=1
|
||||
Oct 1 10:32:54 INFO Waiting for Deployment my-gitea to become ready controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:32:54 INFO Waiting for Deployment ingress-nginx-controller to become ready controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:33:24 INFO Waiting for Deployment my-gitea to become ready controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:33:24 INFO Waiting for Deployment ingress-nginx-controller to become ready controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:33:54 INFO Waiting for Deployment my-gitea to become ready controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:34:24 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:34:24 INFO expected annotation, cnoe.io/last-observed-cli-start-time, not found controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:34:24 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=6fc396d4-e0d5-4c80-aaee-20c1bbffea54
|
||||
Oct 1 10:34:25 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=0667fa85-af1c-403f-bcd9-16ff8f2fad7e
|
||||
Oct 1 10:34:25 INFO expected annotation, cnoe.io/last-observed-cli-start-time, not found controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=0667fa85-af1c-403f-bcd9-16ff8f2fad7e
|
||||
Oct 1 10:34:25 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=0667fa85-af1c-403f-bcd9-16ff8f2fad7e
|
||||
Oct 1 10:34:40 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=ec720aeb-02cd-4974-a991-cf2f19ce8536
|
||||
Oct 1 10:34:40 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=ec720aeb-02cd-4974-a991-cf2f19ce8536
|
||||
Oct 1 10:34:40 INFO Shutting Down controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=ec720aeb-02cd-4974-a991-cf2f19ce8536
|
||||
Oct 1 10:34:40 INFO Stopping and waiting for non leader election runnables
|
||||
Oct 1 10:34:40 INFO Stopping and waiting for leader election runnables
|
||||
Oct 1 10:34:40 INFO Shutdown signal received, waiting for all workers to finish controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
Oct 1 10:34:40 INFO Shutdown signal received, waiting for all workers to finish controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
Oct 1 10:34:40 INFO All workers finished controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
Oct 1 10:34:40 INFO Shutdown signal received, waiting for all workers to finish controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
Oct 1 10:34:40 INFO All workers finished controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
Oct 1 10:34:40 INFO All workers finished controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
Oct 1 10:34:40 INFO Stopping and waiting for caches
|
||||
Oct 1 10:34:40 INFO Stopping and waiting for webhooks
|
||||
Oct 1 10:34:40 INFO Stopping and waiting for HTTP servers
|
||||
Oct 1 10:34:40 INFO Wait completed, proceeding to shutdown the manager
|
||||
|
||||
|
||||
########################### Finished Creating IDP Successfully! ############################
|
||||
|
||||
|
||||
Can Access ArgoCD at https://cnoe.localtest.me:8443/argocd
|
||||
Username: admin
|
||||
Password can be retrieved by running: idpbuilder get secrets -p argocd
|
||||
```
|
||||
|
||||
##### ArgoCD applications
|
||||
|
||||
When running idpbuilder 'barely' (without package option) you get the 'core applications' deployed in your cluster:
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/ipceicis-developerframework$ k get applications -A
|
||||
NAMESPACE NAME SYNC STATUS HEALTH STATUS
|
||||
argocd argocd Synced Healthy
|
||||
argocd gitea Synced Healthy
|
||||
argocd nginx Synced Healthy
|
||||
```
|
||||
|
||||
##### ArgoCD UI
|
||||
|
||||
Open ArgoCD locally:
|
||||
|
||||
https://cnoe.localtest.me:8443/argocd
|
||||
|
||||
|
||||
|
||||
Next find the provided credentials for ArgoCD (here: argocd-initial-admin-secret):
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/idpbuilder$ ib get secrets
|
||||
---------------------------
|
||||
Name: argocd-initial-admin-secret
|
||||
Namespace: argocd
|
||||
Data:
|
||||
password : 2MoMeW30wSC9EraF
|
||||
username : admin
|
||||
---------------------------
|
||||
Name: gitea-credential
|
||||
Namespace: gitea
|
||||
Data:
|
||||
password : LI$T?o>N{-<|{^dm$eTg*gni1(2:Y0@q344yqQIS
|
||||
username : giteaAdmin
|
||||
```
|
||||
|
||||
In ArgoCD you will see the deployed three applications of the core package:
|
||||
|
||||
|
||||
|
||||
### Second run: Append 'package1' from the CNOE-stacks repo
|
||||
|
||||
CNOE provides example packages in `https://github.com/cnoe-io/stacks.git`. Having cloned this repo you can locally refer to theses packages:
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ git remote -v
|
||||
origin https://github.com/cnoe-io/stacks.git (fetch)
|
||||
origin https://github.com/cnoe-io/stacks.git (push)
|
||||
```
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ls -al
|
||||
total 64
|
||||
drwxr-xr-x 12 stl stl 4096 Sep 28 13:55 .
|
||||
drwxr-xr-x 26 stl stl 4096 Sep 30 11:53 ..
|
||||
drwxr-xr-x 8 stl stl 4096 Sep 28 13:56 .git
|
||||
drwxr-xr-x 4 stl stl 4096 Jul 29 10:57 .github
|
||||
-rw-r--r-- 1 stl stl 11341 Sep 28 09:12 LICENSE
|
||||
-rw-r--r-- 1 stl stl 1079 Sep 28 13:55 README.md
|
||||
drwxr-xr-x 4 stl stl 4096 Jul 29 10:57 basic
|
||||
drwxr-xr-x 4 stl stl 4096 Sep 14 15:54 crossplane-integrations
|
||||
drwxr-xr-x 3 stl stl 4096 Aug 13 14:52 dapr-integration
|
||||
drwxr-xr-x 3 stl stl 4096 Sep 14 15:54 jupyterhub
|
||||
drwxr-xr-x 6 stl stl 4096 Aug 16 14:36 local-backup
|
||||
drwxr-xr-x 3 stl stl 4096 Aug 16 14:36 localstack-integration
|
||||
drwxr-xr-x 8 stl stl 4096 Sep 28 13:02 ref-implementation
|
||||
drwxr-xr-x 2 stl stl 4096 Aug 16 14:36 terraform-integrations
|
||||
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ls -al basic/
|
||||
total 20
|
||||
drwxr-xr-x 4 stl stl 4096 Jul 29 10:57 .
|
||||
drwxr-xr-x 12 stl stl 4096 Sep 28 13:55 ..
|
||||
-rw-r--r-- 1 stl stl 632 Jul 29 10:57 README.md
|
||||
drwxr-xr-x 3 stl stl 4096 Jul 29 10:57 package1
|
||||
drwxr-xr-x 2 stl stl 4096 Jul 29 10:57 package2
|
||||
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ls -al basic/package1
|
||||
total 16
|
||||
drwxr-xr-x 3 stl stl 4096 Jul 29 10:57 .
|
||||
drwxr-xr-x 4 stl stl 4096 Jul 29 10:57 ..
|
||||
-rw-r--r-- 1 stl stl 655 Jul 29 10:57 app.yaml
|
||||
drwxr-xr-x 2 stl stl 4096 Jul 29 10:57 manifests
|
||||
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ls -al basic/package2
|
||||
total 16
|
||||
drwxr-xr-x 2 stl stl 4096 Jul 29 10:57 .
|
||||
drwxr-xr-x 4 stl stl 4096 Jul 29 10:57 ..
|
||||
-rw-r--r-- 1 stl stl 498 Jul 29 10:57 app.yaml
|
||||
-rw-r--r-- 1 stl stl 500 Jul 29 10:57 app2.yaml
|
||||
```
|
||||
|
||||
#### Output
|
||||
|
||||
Now we run idpbuilder the second time with `-p basic/package1`
|
||||
|
||||
##### idpbuilder log
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ib create --use-path-routing -p basic/package1
|
||||
Oct 1 12:09:27 INFO Creating kind cluster logger=setup
|
||||
Oct 1 12:09:27 INFO Runtime detected logger=setup provider=docker
|
||||
Oct 1 12:09:27 INFO Cluster already exists logger=setup cluster=localdev
|
||||
Oct 1 12:09:28 INFO Adding CRDs to the cluster logger=setup
|
||||
Oct 1 12:09:28 INFO Setting up CoreDNS logger=setup
|
||||
Oct 1 12:09:28 INFO Setting up TLS certificate logger=setup
|
||||
Oct 1 12:09:28 INFO Creating localbuild resource logger=setup
|
||||
Oct 1 12:09:28 INFO Starting EventSource controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild source=kind source: *v1alpha1.Localbuild
|
||||
Oct 1 12:09:28 INFO Starting Controller controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
Oct 1 12:09:28 INFO Starting EventSource controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage source=kind source: *v1alpha1.CustomPackage
|
||||
Oct 1 12:09:28 INFO Starting Controller controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
Oct 1 12:09:28 INFO Starting EventSource controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository source=kind source: *v1alpha1.GitRepository
|
||||
Oct 1 12:09:28 INFO Starting Controller controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
Oct 1 12:09:28 INFO Starting workers controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild worker count=1
|
||||
Oct 1 12:09:28 INFO Starting workers controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository worker count=1
|
||||
Oct 1 12:09:28 INFO Starting workers controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage worker count=1
|
||||
Oct 1 12:09:29 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=0ed7ccc2-dec7-4ab8-909c-791a7d1b67a8
|
||||
Oct 1 12:09:29 INFO unknown field "status.history[0].initiatedBy" logger=KubeAPIWarningLogger
|
||||
Oct 1 12:09:29 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=0ed7ccc2-dec7-4ab8-909c-791a7d1b67a8
|
||||
Oct 1 12:09:29 ERROR failed updating repo status controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage name=app-my-app namespace=idpbuilder-localdev namespace=idpbuilder-localdev name=app-my-app reconcileID=f9873560-5dcd-4e59-b6f7-ce5d1029ef3d err=Operation cannot be fulfilled on custompackages.idpbuilder.cnoe.io "app-my-app": the object has been modified; please apply your changes to the latest version and try again
|
||||
Oct 1 12:09:29 ERROR Reconciler error controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage name=app-my-app namespace=idpbuilder-localdev namespace=idpbuilder-localdev name=app-my-app reconcileID=f9873560-5dcd-4e59-b6f7-ce5d1029ef3d err=updating argocd application object my-app: Operation cannot be fulfilled on applications.argoproj.io "my-app": the object has been modified; please apply your changes to the latest version and try again
|
||||
Oct 1 12:09:31 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=531cc2d4-6250-493a-aca8-fecf048a608d
|
||||
Oct 1 12:09:31 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=531cc2d4-6250-493a-aca8-fecf048a608d
|
||||
Oct 1 12:09:44 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=022b9813-8708-4f4e-90d7-38f1e114c46f
|
||||
Oct 1 12:09:44 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=022b9813-8708-4f4e-90d7-38f1e114c46f
|
||||
Oct 1 12:10:00 INFO installing bootstrap apps to ArgoCD controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=79a85c21-42c1-41ec-ad03-2bb77aeae027
|
||||
Oct 1 12:10:00 INFO Checking if we should shutdown controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=79a85c21-42c1-41ec-ad03-2bb77aeae027
|
||||
Oct 1 12:10:00 INFO Shutting Down controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild name=localdev name=localdev reconcileID=79a85c21-42c1-41ec-ad03-2bb77aeae027
|
||||
Oct 1 12:10:00 INFO Stopping and waiting for non leader election runnables
|
||||
Oct 1 12:10:00 INFO Stopping and waiting for leader election runnables
|
||||
Oct 1 12:10:00 INFO Shutdown signal received, waiting for all workers to finish controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
Oct 1 12:10:00 INFO Shutdown signal received, waiting for all workers to finish controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
Oct 1 12:10:00 INFO All workers finished controller=custompackage controllerGroup=idpbuilder.cnoe.io controllerKind=CustomPackage
|
||||
Oct 1 12:10:00 INFO Shutdown signal received, waiting for all workers to finish controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
Oct 1 12:10:00 INFO All workers finished controller=localbuild controllerGroup=idpbuilder.cnoe.io controllerKind=Localbuild
|
||||
Oct 1 12:10:00 INFO All workers finished controller=gitrepository controllerGroup=idpbuilder.cnoe.io controllerKind=GitRepository
|
||||
Oct 1 12:10:00 INFO Stopping and waiting for caches
|
||||
Oct 1 12:10:00 INFO Stopping and waiting for webhooks
|
||||
Oct 1 12:10:00 INFO Stopping and waiting for HTTP servers
|
||||
Oct 1 12:10:00 INFO Wait completed, proceeding to shutdown the manager
|
||||
|
||||
|
||||
########################### Finished Creating IDP Successfully! ############################
|
||||
|
||||
|
||||
Can Access ArgoCD at https://cnoe.localtest.me:8443/argocd
|
||||
Username: admin
|
||||
Password can be retrieved by running: idpbuilder get secrets -p argocd
|
||||
```
|
||||
|
||||
##### ArgoCD applications
|
||||
|
||||
Now we have additionally the 'my-app' deployed in the cluster:
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~$ k get applications -A
|
||||
NAMESPACE NAME SYNC STATUS HEALTH STATUS
|
||||
argocd argocd Synced Healthy
|
||||
argocd gitea Synced Healthy
|
||||
argocd my-app Synced Healthy
|
||||
argocd nginx Synced Healthy
|
||||
```
|
||||
|
||||
##### ArgoCD UI
|
||||
|
||||
|
||||
|
||||
### Third run: Finally we append 'ref-implementation' from the CNOE-stacks repo
|
||||
|
||||
We finally append the so called ['reference-implementation'](https://cnoe.io/docs/reference-implementation/integrations/reference-impl), which provides a real basic IDP:
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ib create --use-path-routing -p ref-implementation
|
||||
```
|
||||
|
||||
##### ArgoCD applications
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~$ k get applications -A
|
||||
NAMESPACE NAME SYNC STATUS HEALTH STATUS
|
||||
argocd argo-workflows Synced Healthy
|
||||
argocd argocd Synced Healthy
|
||||
argocd backstage Synced Healthy
|
||||
argocd included-backstage-templates Synced Healthy
|
||||
argocd external-secrets Synced Healthy
|
||||
argocd gitea Synced Healthy
|
||||
argocd keycloak Synced Healthy
|
||||
argocd metric-server Synced Healthy
|
||||
argocd my-app Synced Healthy
|
||||
argocd nginx Synced Healthy
|
||||
argocd spark-operator Synced Healthy
|
||||
```
|
||||
|
||||
##### ArgoCD UI
|
||||
|
||||
ArgoCD shows all provissioned applications:
|
||||
|
||||
|
||||
|
||||
##### Keycloak UI
|
||||
|
||||
In our cluster there is also keycloak as IAM provisioned.
|
||||
Login into Keycloak with 'cnoe-admin' and the KEYCLOAK_ADMIN_PASSWORD.
|
||||
|
||||
These credentails are defined in the package:
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ cat ref-implementation/keycloak/manifests/keycloak-config.yaml | grep -i admin
|
||||
group-admin-payload.json: |
|
||||
{"name":"admin"}
|
||||
"/admin"
|
||||
ADMIN_PASSWORD=$(cat /var/secrets/KEYCLOAK_ADMIN_PASSWORD)
|
||||
--data-urlencode "username=cnoe-admin" \
|
||||
--data-urlencode "password=${ADMIN_PASSWORD}" \
|
||||
```
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/cnoe-stacks$ ib get secrets
|
||||
---------------------------
|
||||
Name: argocd-initial-admin-secret
|
||||
Namespace: argocd
|
||||
Data:
|
||||
password : 2MoMeW30wSC9EraF
|
||||
username : admin
|
||||
---------------------------
|
||||
Name: gitea-credential
|
||||
Namespace: gitea
|
||||
Data:
|
||||
password : LI$T?o>N{-<|{^dm$eTg*gni1(2:Y0@q344yqQIS
|
||||
username : giteaAdmin
|
||||
---------------------------
|
||||
Name: keycloak-config
|
||||
Namespace: keycloak
|
||||
Data:
|
||||
KC_DB_PASSWORD : k3-1kgxxd/X2Cw//pX-uKMsmgWogEz5YGnb5
|
||||
KC_DB_USERNAME : keycloak
|
||||
KEYCLOAK_ADMIN_PASSWORD : zMSjv5eA0l/+0-MDAaaNe+rHRMrB2q0NssP-
|
||||
POSTGRES_DB : keycloak
|
||||
POSTGRES_PASSWORD : k3-1kgxxd/X2Cw//pX-uKMsmgWogEz5YGnb5
|
||||
POSTGRES_USER : keycloak
|
||||
USER_PASSWORD : Kd+0+/BqPRAvnLPZO-L2o/6DoBrzUeMsr29U
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
##### Backstage UI
|
||||
|
||||
As Backstage login you either can use the 'user1' with `USER_PASSWORD : Kd+0+/BqPRAvnLPZO-L2o/6DoBrzUeMsr29U` or you create a new user in keycloak
|
||||
|
||||
|
||||
|
||||
We create user 'ipcei' and also set a password (in tab 'Credentials'):
|
||||
|
||||
|
||||
|
||||
Now we can log into backstage (rember: you could have already existing usr 'user1'):
|
||||
|
||||
|
||||
|
||||
and see the basic setup of the Backstage portal:
|
||||
|
||||
|
||||
|
||||
### Use a Golden Path: 'Basic Deployment'
|
||||
|
||||
Now we want to use the Backstage portal as a developer. We create in Backstage our own platform based activity by using the golden path template 'Basic Deployment:
|
||||
|
||||
|
||||
|
||||
When we run it, we see 'golden path activities'
|
||||
|
||||
|
||||
|
||||
which finally result in a new catalogue entry:
|
||||
|
||||
|
||||
|
||||
#### Software development lifecycle
|
||||
|
||||
When we follow the 'view source' link we are directly linked to the git repo of our newly created application:
|
||||
|
||||
|
||||
|
||||
Check it out by cloning into a local git repo (watch the GIT_SSL_NO_VERIFY=true env setting):
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/idp-temporary$ GIT_SSL_NO_VERIFY=true git clone https://cnoe.localtest.me:8443/gitea/giteaAdmin/basicdeployment.git
|
||||
Cloning into 'basicdeployment'...
|
||||
remote: Enumerating objects: 10, done.
|
||||
remote: Counting objects: 100% (10/10), done.
|
||||
remote: Compressing objects: 100% (8/8), done.
|
||||
remote: Total 10 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
|
||||
Receiving objects: 100% (10/10), 47.62 KiB | 23.81 MiB/s, done.
|
||||
|
||||
stl@ubuntu-vpn:~/git/mms/idp-temporary$ cd basicdeployment/
|
||||
|
||||
stl@ubuntu-vpn:~/git/mms/idp-temporary/basicdeployment$ ll
|
||||
total 24
|
||||
drwxr-xr-x 5 stl stl 4096 Oct 1 13:00 ./
|
||||
drwxr-xr-x 4 stl stl 4096 Oct 1 13:00 ../
|
||||
drwxr-xr-x 8 stl stl 4096 Oct 1 13:00 .git/
|
||||
-rw-r--r-- 1 stl stl 928 Oct 1 13:00 catalog-info.yaml
|
||||
drwxr-xr-x 3 stl stl 4096 Oct 1 13:00 docs/
|
||||
drwxr-xr-x 2 stl stl 4096 Oct 1 13:00 manifests/
|
||||
```
|
||||
|
||||
#### Edit and change
|
||||
|
||||
Change some things, like the decription and the replicas:
|
||||
|
||||
|
||||
|
||||
#### Push
|
||||
|
||||
Push your changes, use the giteaAdmin user to authenticate:
|
||||
|
||||
```bash
|
||||
stl@ubuntu-vpn:~/git/mms/idp-temporary/basicdeployment$ ib get secrets
|
||||
---------------------------
|
||||
Name: argocd-initial-admin-secret
|
||||
Namespace: argocd
|
||||
Data:
|
||||
password : 2MoMeW30wSC9EraF
|
||||
username : admin
|
||||
---------------------------
|
||||
Name: gitea-credential
|
||||
Namespace: gitea
|
||||
Data:
|
||||
password : LI$T?o>N{-<|{^dm$eTg*gni1(2:Y0@q344yqQIS
|
||||
username : giteaAdmin
|
||||
---------------------------
|
||||
Name: keycloak-config
|
||||
Namespace: keycloak
|
||||
Data:
|
||||
KC_DB_PASSWORD : k3-1kgxxd/X2Cw//pX-uKMsmgWogEz5YGnb5
|
||||
KC_DB_USERNAME : keycloak
|
||||
KEYCLOAK_ADMIN_PASSWORD : zMSjv5eA0l/+0-MDAaaNe+rHRMrB2q0NssP-
|
||||
POSTGRES_DB : keycloak
|
||||
POSTGRES_PASSWORD : k3-1kgxxd/X2Cw//pX-uKMsmgWogEz5YGnb5
|
||||
POSTGRES_USER : keycloak
|
||||
USER_PASSWORD : Kd+0+/BqPRAvnLPZO-L2o/6DoBrzUeMsr29U
|
||||
stl@ubuntu-vpn:~/git/mms/idp-temporary/basicdeployment$ GIT_SSL_NO_VERIFY=true git push
|
||||
Username for 'https://cnoe.localtest.me:8443': giteaAdmin
|
||||
Password for 'https://giteaAdmin@cnoe.localtest.me:8443':
|
||||
Enumerating objects: 5, done.
|
||||
Counting objects: 100% (5/5), done.
|
||||
Delta compression using up to 8 threads
|
||||
Compressing objects: 100% (3/3), done.
|
||||
Writing objects: 100% (3/3), 382 bytes | 382.00 KiB/s, done.
|
||||
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
|
||||
remote: . Processing 1 references
|
||||
remote: Processed 1 references in total
|
||||
To https://cnoe.localtest.me:8443/gitea/giteaAdmin/basicdeployment.git
|
||||
69244d6..1269617 main -> main
|
||||
```
|
||||
|
||||
#### Wait for gitops magic: deployment into the 'production' cluster
|
||||
|
||||
Next wait a bit until Gitops does its magic and our 'wanted' state in the repo gets automatically deployed to the 'production' cluster:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
### What comes next?
|
||||
|
||||
The showtime of CNOE high level behaviour and usage scenarios is now finished. We setup an initial IDP and used a backstage golden path to init and deploy a simple application.
|
||||
|
||||
[Last not least](../conclusio/) we want to sum up the whole way from Devops to 'Frameworking' (is this the correct wording???)
|
||||
{{% /pageinfo %}}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 174 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 196 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 188 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 243 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 79 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 275 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 190 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 66 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 207 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 397 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 137 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 118 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 152 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 372 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 766 KiB |
|
|
@ -1,18 +0,0 @@
|
|||
// how to create/export c4 images:
|
||||
// see also https://likec4.dev/tooling/cli/
|
||||
|
||||
docker run -it --rm --name likec4 --user node -v $PWD:/app node bash
|
||||
npm install likec4
|
||||
exit
|
||||
|
||||
docker commit likec4 likec4
|
||||
docker run -it --rm --user node -v $PWD:/app -p 5173:5173 likec4 bash
|
||||
|
||||
// as root
|
||||
npx playwright install-deps
|
||||
npx playwright install
|
||||
|
||||
npm install likec4
|
||||
|
||||
// render
|
||||
node@e20899c8046f:/app/content/en/docs/project/onboarding$ ./node_modules/.bin/likec4 export png -o ./images .
|
||||
|
|
@ -1,35 +0,0 @@
|
|||
---
|
||||
title: Conclusio
|
||||
weight: 7
|
||||
description: 'Summary and final thoughts: Always challenge theses concepts, accumptions and claims!'
|
||||
---
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
|
||||
## Summary
|
||||
|
||||
In the project 'Edge Developer Framework' we start with DevOps, set platforms on top to automate golden paths, and finally set 'frameworks' (aka Orchestrators') on top to have declarative,automated and reconcilable platforms.
|
||||
|
||||
{{% /pageinfo %}}
|
||||
|
||||
|
||||
## From Devops over Platform to Framework Engineering
|
||||
|
||||
We come along from a quite well known, but already complex discipline called 'Platform Engineering', which is the next level devops.
|
||||
On top of these two domains we now have 'Framework Engineering', i.e. buildung dynamic, orchestrated and reconciling platforms:
|
||||
|
||||
| Classic Platform engineering | New: Framework Orchestration on top of Platforms | Your job: Framework Engineer |
|
||||
| -- | -- | -- |
|
||||
| <img src="./images/layers-and-platform-engineer.png" width="200"> |<img src="./images/layers.png" width="200"> | <img src="./images/layers-and-framework-engineer.png" width="200"> |
|
||||
|
||||
## The whole picture of engineering
|
||||
|
||||
So always keep in mind that as as 'Framework Engineer' you
|
||||
|
||||
* include the skills of a platform and a devops engineer,
|
||||
* you do Framework, Platform and Devops Engineering at the same time
|
||||
* and your results have impact on Frameworks, Platforms and Devops tools, layers, processes.
|
||||
|
||||
The following diamond is illustrating this: on top is you, on the bottom is our baseline 'DevOps'
|
||||
|
||||
<img src="./images/modern.png" width="600">
|
||||
|
|
@ -1,102 +0,0 @@
|
|||
specification {
|
||||
tag engineering
|
||||
element domain
|
||||
element engineer {
|
||||
style {
|
||||
shape person
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
model {
|
||||
|
||||
engineer framework-engineer 'Framework Engineer' 'Build and maintain one platform orchestrating framework'{
|
||||
style {
|
||||
color: sky
|
||||
}
|
||||
-> framework-engineering
|
||||
-> platform-engineer
|
||||
}
|
||||
|
||||
domain framework-engineering 'Framework Engineering' 'Building and maintaining frameworks'{
|
||||
#engineering
|
||||
style {
|
||||
color: sky
|
||||
}
|
||||
-> framework
|
||||
-> platform-engineering
|
||||
}
|
||||
|
||||
domain framework '"Framework" (IPCEI wording!)' 'A platform defining system' {
|
||||
style {
|
||||
color: sky
|
||||
}
|
||||
-> platform
|
||||
}
|
||||
|
||||
engineer platform-engineer 'Platform Engineer' {
|
||||
style {
|
||||
color: indigo
|
||||
}
|
||||
-> platform-engineering
|
||||
-> devops-engineer
|
||||
}
|
||||
|
||||
domain platform-engineering 'Platform Engineering' 'Building and maintaining platforms' {
|
||||
#engineering
|
||||
style {
|
||||
color: indigo
|
||||
}
|
||||
-> platform
|
||||
-> devops-engineering
|
||||
}
|
||||
|
||||
domain platform 'Platform' 'A Devops defining system' {
|
||||
style {
|
||||
color: indigo
|
||||
}
|
||||
-> devops
|
||||
}
|
||||
|
||||
engineer devops-engineer 'Devops Engineer' {
|
||||
style {
|
||||
color: amber
|
||||
}
|
||||
-> devops-engineering
|
||||
}
|
||||
|
||||
domain devops-engineering 'Devops Engineering' 'Building and maintaining devops means' {
|
||||
#engineering
|
||||
style {
|
||||
color: amber
|
||||
}
|
||||
-> devops
|
||||
}
|
||||
domain devops 'Devops' 'A software lifecycle enabling tool and process setup' {
|
||||
style {
|
||||
color: amber
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
views {
|
||||
view modern {
|
||||
title 'Modern Devops'
|
||||
description 'Devops is abstarcted by Platforms, Platforms are abstracted by Frameworks (IPCEI wording!)'
|
||||
include element.kind==domain, element.kind==engineer
|
||||
|
||||
}
|
||||
|
||||
view layers {
|
||||
include devops, platform, framework
|
||||
}
|
||||
|
||||
view layers-and-framework-engineer {
|
||||
include devops, platform, framework, framework-engineering, framework-engineer
|
||||
}
|
||||
|
||||
view layers-and-platform-engineer {
|
||||
include devops, platform, platform-engineering, platform-engineer
|
||||
}
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 100 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 224 KiB |
|
|
@ -1,9 +0,0 @@
|
|||
---
|
||||
title: 'Platform 101: Conceptual Onboarding '
|
||||
linktitle: Conceptual Onboarding
|
||||
weight: 20
|
||||
description: How to conceptually onboard onto the Edge Developer Framework (EDF) requirements and the designed solution
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
|
||||
## Storyline
|
||||
|
||||
1. We have the 'Developer Framework'
|
||||
2. We think the solution for DF is 'Platforming' (Digital Platforms)
|
||||
1. The next evolution after DevOps
|
||||
2. Gartner predicts 80% of SWE companies to have platforms in 2026
|
||||
3. Platforms have a history since roundabout 2019
|
||||
4. CNCF has a working group which created capabilities and a maturity model
|
||||
3. Platforms evolve - nowadys there are Platform Orchestrators
|
||||
1. Humanitec set up a Reference Architecture
|
||||
2. There is this 'Orchestrator' thing - declaratively describe, customize and change platforms!
|
||||
4. Mapping our assumptions to solutions
|
||||
1. CNOE is a hot candidate to help and fulfill our platform building
|
||||
2. CNOE aims to embrace change and customization!
|
||||
5. Showtime CNOE
|
||||
|
||||
|
||||
## Challenges
|
||||
|
||||
1. Don't miss to further investigate and truely understand **DF needs**
|
||||
2. Don't miss to further investigate and truely understand **Platform capabilities**
|
||||
3. Don't miss to further investigate and truely understand **Platform orchestration**
|
||||
3. Don't miss to further investigate and truely understand **CNOE solution**
|
||||
|
||||
## Architecture
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 114 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 114 KiB |
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue