170 lines
5 KiB
Markdown
170 lines
5 KiB
Markdown
# STACKIT Docs Integration
|
|
|
|
This document describes how Professional Services Terraform examples are synced as `.mdx` asset cards to the STACKIT documentation assetcontainer.
|
|
|
|
## Overview
|
|
|
|
Each example in `examples/` declares metadata in `stackit.docs.yaml`. On merge to `main`, a GitHub Actions workflow generates `.mdx` asset files and opens a PR to the `stackitcloud/docs-content` repository under `docs/cloud-framework/architecture-framework/assetcontainer/professional-services/`.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
professional-service/
|
|
├── examples/
|
|
│ ├── alb-tls-examples/
|
|
│ │ ├── README.md
|
|
│ │ ├── stackit.docs.yaml # <-- metadata for docs card
|
|
│ │ └── ...
|
|
│ ├── ske-azure-arc-integration/
|
|
│ │ ├── README.md
|
|
│ │ ├── stackit.docs.yaml # <-- metadata for docs card
|
|
│ │ └── ...
|
|
│ └── ...
|
|
├── ci-scripts/
|
|
│ ├── aggregate_docs.py # generates .mdx files + _meta.yml
|
|
│ └── sync-stackit-docs.sh # CI: clone docs, copy files, PR
|
|
└── STACKIT-DOCS.md # this file
|
|
```
|
|
|
|
## stackit.docs.yaml Format
|
|
|
|
Each example must contain:
|
|
|
|
```yaml
|
|
headline: Example Title
|
|
description: Short description of what the example demonstrates.
|
|
tags:
|
|
- ske
|
|
- kubernetes
|
|
- terraform
|
|
```
|
|
|
|
| Field | Required | Description |
|
|
| ------------- | -------- | ----------------------------------------- |
|
|
| `headline` | Yes | Title displayed on the asset card |
|
|
| `description` | Yes | Brief summary (1-2 sentences) on the card |
|
|
| `tags` | Yes | Tags for filtering (shown on card, max 5) |
|
|
|
|
## Generated .mdx Format
|
|
|
|
Each `stackit.docs.yaml` is transformed into an `.mdx` file with `frameworkAsset` frontmatter:
|
|
|
|
```mdx
|
|
---
|
|
title: SKE Azure Arc Integration
|
|
description: Terraform and CLI steps to connect a STACKIT SKE cluster to Azure Arc.
|
|
hideBreadcrumbs: true
|
|
sidebar:
|
|
hidden: true
|
|
frameworkAsset:
|
|
owner: Professional Services
|
|
managed: true
|
|
category: guide
|
|
external: true
|
|
recommended: true
|
|
tags:
|
|
- ske
|
|
- azure
|
|
- terraform
|
|
---
|
|
|
|
import { Card } from "@astrojs/starlight/components";
|
|
|
|
# SKE Azure Arc Integration
|
|
|
|
...
|
|
```
|
|
|
|
## CI Process
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[Developer adds/updates<br>stackit.docs.yaml] --> B[PR to professional-services]
|
|
B --> Merged{Merged to main?}
|
|
Merged -->|Yes| C[GitHub Actions triggered]
|
|
Merged -->|No| B
|
|
C --> D[aggregate_docs.py<br>generates .mdx files + _meta.yml]
|
|
D --> E[Clone docs-content repo]
|
|
E --> F[Copy .mdx files to<br>assetcontainer/professional-services/]
|
|
F --> G{Any file changes<br>vs current docs?}
|
|
G -->|No| H[Exit: docs up to date]
|
|
G -->|Yes| I[Create feature branch<br>autopr/sync-professional-service-examples]
|
|
I --> J[Commit + push changes]
|
|
J --> K[Create PR to docs-content]
|
|
K --> L[Review and merge on<br>docs-content side]
|
|
```
|
|
|
|
## Adding a New Example
|
|
|
|
1. Create a new directory under `examples/`
|
|
2. Add your Terraform code and `README.md`
|
|
3. Create `stackit.docs.yaml` with the required fields:
|
|
|
|
```yaml
|
|
headline: My New Example
|
|
description: Demonstrates how to deploy X on STACKIT using Y.
|
|
tags:
|
|
- ske
|
|
- terraform
|
|
- my-tag
|
|
```
|
|
|
|
4. Open a PR to this repository
|
|
5. Once merged, the CI will automatically:
|
|
- Generate `.mdx` asset files from all `stackit.docs.yaml` files
|
|
- Clone the `docs-content` repository
|
|
- Copy files to `assetcontainer/professional-services/`
|
|
- Open a PR if content has changed
|
|
|
|
## Scripts
|
|
|
|
### aggregate_docs.py
|
|
|
|
The Python script:
|
|
|
|
- Scans `examples/*/stackit.docs.yaml`
|
|
- Generates `.mdx` files with `frameworkAsset` frontmatter
|
|
- Generates `_meta.yml` for the assetcontainer
|
|
|
|
Run locally to preview:
|
|
|
|
```bash
|
|
python3 ci-scripts/aggregate_docs.py
|
|
ls .generated-mdx/professional-services/
|
|
cat .generated-mdx/professional-services/ps-my-example.mdx
|
|
```
|
|
|
|
### sync-stackit-docs.sh
|
|
|
|
The CI entrypoint:
|
|
|
|
- Calls `aggregate_docs.py` to generate `.mdx` files
|
|
- Clones `stackitcloud/docs-content`
|
|
- Copies generated files to `assetcontainer/professional-services/`
|
|
- Creates a PR if changes are detected
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
| -------------------- | -------- | ------------------------------------------------------- |
|
|
| `STACKIT_DOCS_TOKEN` | Yes | GitHub PAT with repo write permissions |
|
|
| `STACKIT_DOCS_REPO` | No | Target docs repo (default: `stackitcloud/docs-content`) |
|
|
|
|
### Manual Execution
|
|
|
|
```bash
|
|
export STACKIT_DOCS_TOKEN=<your-github-pat>
|
|
bash ci-scripts/sync-stackit-docs.sh
|
|
```
|
|
|
|
## GitHub Actions Secret
|
|
|
|
To enable the CI workflow, add the following secret to the repository:
|
|
|
|
- **Secret name:** `STACKIT_DOCS_TOKEN`
|
|
- **Value:** GitHub Personal Access Token with `repo` scope
|
|
|
|
The workflow (`.github/workflows/sync-stackit-docs.yaml`) triggers on:
|
|
|
|
- Every push to `main` that modifies `examples/**/stackit.docs.yaml`
|
|
- Manual trigger via the GitHub Actions UI
|