From 0813485ac7591ff4d12417b8dd1d303816840657 Mon Sep 17 00:00:00 2001 From: Valentin Gerlach Date: Wed, 20 Aug 2025 16:06:11 +0200 Subject: [PATCH 1/2] ci: prose linting using Vale --- .github/styles/Google/AMPM.yml | 9 + .github/styles/Google/Acronyms.yml | 64 +++++++ .github/styles/Google/Colons.yml | 8 + .github/styles/Google/Contractions.yml | 30 +++ .github/styles/Google/DateFormat.yml | 9 + .github/styles/Google/Ellipses.yml | 9 + .github/styles/Google/EmDash.yml | 13 ++ .github/styles/Google/Exclamation.yml | 12 ++ .github/styles/Google/FirstPerson.yml | 13 ++ .github/styles/Google/Gender.yml | 9 + .github/styles/Google/GenderBias.yml | 43 +++++ .github/styles/Google/HeadingPunctuation.yml | 13 ++ .github/styles/Google/Headings.yml | 29 +++ .github/styles/Google/Latin.yml | 11 ++ .github/styles/Google/LyHyphens.yml | 14 ++ .github/styles/Google/OptionalPlurals.yml | 12 ++ .github/styles/Google/Ordinal.yml | 7 + .github/styles/Google/OxfordComma.yml | 7 + .github/styles/Google/Parens.yml | 7 + .github/styles/Google/Passive.yml | 184 +++++++++++++++++++ .github/styles/Google/Periods.yml | 7 + .github/styles/Google/Quotes.yml | 7 + .github/styles/Google/Ranges.yml | 7 + .github/styles/Google/Semicolons.yml | 8 + .github/styles/Google/Slang.yml | 11 ++ .github/styles/Google/Spacing.yml | 10 + .github/styles/Google/Spelling.yml | 10 + .github/styles/Google/Units.yml | 8 + .github/styles/Google/We.yml | 11 ++ .github/styles/Google/Will.yml | 7 + .github/styles/Google/WordList.yml | 80 ++++++++ .github/styles/Google/meta.json | 4 + .github/styles/Google/vocab.txt | 0 .github/workflows/vale.yml | 11 ++ .vale.ini | 7 + 35 files changed, 691 insertions(+) create mode 100644 .github/styles/Google/AMPM.yml create mode 100644 .github/styles/Google/Acronyms.yml create mode 100644 .github/styles/Google/Colons.yml create mode 100644 .github/styles/Google/Contractions.yml create mode 100644 .github/styles/Google/DateFormat.yml create mode 100644 .github/styles/Google/Ellipses.yml create mode 100644 .github/styles/Google/EmDash.yml create mode 100644 .github/styles/Google/Exclamation.yml create mode 100644 .github/styles/Google/FirstPerson.yml create mode 100644 .github/styles/Google/Gender.yml create mode 100644 .github/styles/Google/GenderBias.yml create mode 100644 .github/styles/Google/HeadingPunctuation.yml create mode 100644 .github/styles/Google/Headings.yml create mode 100644 .github/styles/Google/Latin.yml create mode 100644 .github/styles/Google/LyHyphens.yml create mode 100644 .github/styles/Google/OptionalPlurals.yml create mode 100644 .github/styles/Google/Ordinal.yml create mode 100644 .github/styles/Google/OxfordComma.yml create mode 100644 .github/styles/Google/Parens.yml create mode 100644 .github/styles/Google/Passive.yml create mode 100644 .github/styles/Google/Periods.yml create mode 100644 .github/styles/Google/Quotes.yml create mode 100644 .github/styles/Google/Ranges.yml create mode 100644 .github/styles/Google/Semicolons.yml create mode 100644 .github/styles/Google/Slang.yml create mode 100644 .github/styles/Google/Spacing.yml create mode 100644 .github/styles/Google/Spelling.yml create mode 100644 .github/styles/Google/Units.yml create mode 100644 .github/styles/Google/We.yml create mode 100644 .github/styles/Google/Will.yml create mode 100644 .github/styles/Google/WordList.yml create mode 100644 .github/styles/Google/meta.json create mode 100644 .github/styles/Google/vocab.txt create mode 100644 .github/workflows/vale.yml create mode 100644 .vale.ini diff --git a/.github/styles/Google/AMPM.yml b/.github/styles/Google/AMPM.yml new file mode 100644 index 0000000..37b49ed --- /dev/null +++ b/.github/styles/Google/AMPM.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'AM' or 'PM' (preceded by a space)." +link: "https://developers.google.com/style/word-list" +level: error +nonword: true +tokens: + - '\d{1,2}[AP]M\b' + - '\d{1,2} ?[ap]m\b' + - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/.github/styles/Google/Acronyms.yml b/.github/styles/Google/Acronyms.yml new file mode 100644 index 0000000..f41af01 --- /dev/null +++ b/.github/styles/Google/Acronyms.yml @@ -0,0 +1,64 @@ +extends: conditional +message: "Spell out '%s', if it's unfamiliar to the audience." +link: 'https://developers.google.com/style/abbreviations' +level: suggestion +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.github/styles/Google/Colons.yml b/.github/styles/Google/Colons.yml new file mode 100644 index 0000000..4a027c3 --- /dev/null +++ b/.github/styles/Google/Colons.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should be in lowercase." +link: 'https://developers.google.com/style/colons' +nonword: true +level: warning +scope: sentence +tokens: + - '(?=1.0.0" +} diff --git a/.github/styles/Google/vocab.txt b/.github/styles/Google/vocab.txt new file mode 100644 index 0000000..e69de29 diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 0000000..f3e21da --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,11 @@ +name: Vale + +on: [pull_request] + +jobs: + vale: + name: vale + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: errata-ai/vale-action@v2.1.1 diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..73300b6 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,7 @@ +StylesPath = .github/styles +MinAlertLevel = suggestion + +Packages = Google + +[*.md] +BasedOnStyles = Vale, Google From 0f095f35c1230fd35b0ba5bb105ab5e4610c9782 Mon Sep 17 00:00:00 2001 From: Valentin Gerlach Date: Thu, 21 Aug 2025 15:01:38 +0200 Subject: [PATCH 2/2] fix vale warnings --- .../config/vocabularies/openMCP/accept.txt | 15 ++++++++++++++ .vale.ini | 6 +++++- docs/about/concepts/cluster-provider.md | 4 ++-- docs/about/concepts/managed-control-plane.md | 4 ++-- docs/about/concepts/platform-service.md | 4 ++-- docs/about/concepts/service-provider.md | 4 ++-- docs/about/ecosystem.md | 15 +++++++++----- docs/about/project.md | 20 +++++++++++++------ docs/developers/getting-started.md | 10 +++++++++- docs/operators/getting-started.md | 2 +- docs/users/getting-started.md | 2 +- 11 files changed, 63 insertions(+), 23 deletions(-) create mode 100644 .github/styles/config/vocabularies/openMCP/accept.txt diff --git a/.github/styles/config/vocabularies/openMCP/accept.txt b/.github/styles/config/vocabularies/openMCP/accept.txt new file mode 100644 index 0000000..7c197e6 --- /dev/null +++ b/.github/styles/config/vocabularies/openMCP/accept.txt @@ -0,0 +1,15 @@ +[Kk]ubebuilder +[Kk]ustomize +APIs? +Bundesministerium +CRDs? +Crossplane +Energie +für +Hetzner +kubectl +Kyverno +MCPs? +und +Wirtschaft +automations diff --git a/.vale.ini b/.vale.ini index 73300b6..490b7a3 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,7 +1,11 @@ StylesPath = .github/styles MinAlertLevel = suggestion +Vocab = openMCP + Packages = Google -[*.md] +[docs/**/*.md] BasedOnStyles = Vale, Google + +Google.WordList["Cloud"] = NO diff --git a/docs/about/concepts/cluster-provider.md b/docs/about/concepts/cluster-provider.md index 73c72bb..4fe071a 100644 --- a/docs/about/concepts/cluster-provider.md +++ b/docs/about/concepts/cluster-provider.md @@ -1,3 +1,3 @@ -# Cluster Providers +# Cluster providers -Cluster providers are responsible for the dynamic creation, modification, and deletion of Kubernetes clusters in an openMCP environment. They conceal certain cluster technologies (e.g., [Gardener](https://gardener.cloud/) and [Kubernetes-in-Docker](https://kind.sigs.k8s.io/)) behind a homogeneous interface. This allows operators to install an openMCP system in different environments and on various infrastructure providers without having to adjust the other components of the system accordingly. +Cluster providers are responsible for the dynamic creation, modification, and deletion of Kubernetes clusters in an openMCP environment. They conceal certain cluster technologies (for example, [Gardener](https://gardener.cloud/) and [Kubernetes-in-Docker](https://kind.sigs.k8s.io/)) behind a homogeneous interface. This allows operators to install an openMCP system in different environments and on various infrastructure providers without having to adjust the other components of the system accordingly. diff --git a/docs/about/concepts/managed-control-plane.md b/docs/about/concepts/managed-control-plane.md index e58c9f3..2086bf1 100644 --- a/docs/about/concepts/managed-control-plane.md +++ b/docs/about/concepts/managed-control-plane.md @@ -1,3 +1,3 @@ -# Managed Control Planes (MCPs) +# Managed control planes (MCPs) -Managed Control Planes (MCPs) are at the heart of openMCP. Simply put, they are lightweight Kubernetes clusters that store the desired state and current status of various resources. All resources follow the Kubernetes Resource Model (KRM), allowing infrastructure resources, deployments, etc., to be managed with common Kubernetes tools like kubectl, kustomize, Helm, Flux, ArgoCD, and so on. +Managed Control Planes (MCPs) are at the heart of openMCP. Simply put, they're lightweight Kubernetes clusters that store the desired state and current status of various resources. All resources follow the Kubernetes Resource Model (KRM), allowing you to manage infrastructure resources, deployments, etc. using common Kubernetes tools like kubectl, kustomize, Helm, Flux, ArgoCD, and so on. diff --git a/docs/about/concepts/platform-service.md b/docs/about/concepts/platform-service.md index aea5020..e90ade0 100644 --- a/docs/about/concepts/platform-service.md +++ b/docs/about/concepts/platform-service.md @@ -1,3 +1,3 @@ -# Platform Services +# Platform services -Platform services add functionality to an openMCP environment (not MCPs). Examples include network services (Gateway API, Ingress), audit logs, billing, grouping of MCPs, and system-wide policies. They are installed and configured by the platform operator and apply to the entire system. +Platform services add capabilities to an openMCP environment (not MCPs). Examples include network services (Gateway API, Ingress), audit logs, billing, grouping of MCPs, and system-wide policies. They're installed and configured by the platform operator and apply to the entire system. diff --git a/docs/about/concepts/service-provider.md b/docs/about/concepts/service-provider.md index 5bfcf14..32b0876 100644 --- a/docs/about/concepts/service-provider.md +++ b/docs/about/concepts/service-provider.md @@ -1,3 +1,3 @@ -# Service Providers +# Service providers -Without service providers, MCPs are of little use. They add functionality such as cloud provider APIs, GitOps, policies, or backup and restore to MCPs. The operators of an openMCP environment decide which service providers are available to end users. The end users can then activate them for their MCPs. +Without service providers, MCPs are of little use. They add capabilities such as cloud provider APIs, GitOps, policies, or backup and restore to MCPs. The operators of an openMCP environment decide which service providers are available to end users. The end users can then activate them for their MCPs. diff --git a/docs/about/ecosystem.md b/docs/about/ecosystem.md index d2b53a6..d1d4a74 100644 --- a/docs/about/ecosystem.md +++ b/docs/about/ecosystem.md @@ -2,9 +2,12 @@ sidebar_position: 2 --- + + + # Ecosystem -openMCP is a platform built on top of amazing open-source projects. The major ones are listed below. +openMCP is a platform built on top of amazing open source projects. You can find the major ones listed below. ## Kubernetes @@ -12,7 +15,7 @@ openMCP is a platform built on top of amazing open-source projects. The major on ## Gardener -[Gardener](https://gardener.cloud/) delivers "fully-managed clusters at scale everywhere with your own Gardener installation".[^gardener] Supported infrastructure includes AWS, Azure, and GCP but also OpenStack, [IronCore](https://github.com/ironcore-dev/gardener-extension-provider-ironcore), [Hetzner Cloud](https://github.com/23technologies/gardener-extension-provider-hcloud), and others. Like openMCP, Gardener is a Kubernetes extension and "adheres to the same principles for resiliency, manageability, observability and high automation by design".[^gardener] openMCP can use Gardener as a [cluster provider](concepts/cluster-provider.md). +[Gardener](https://gardener.cloud/) delivers "fully managed clusters at scale everywhere with your own Gardener installation."[^gardener] Supported infrastructure includes AWS, Azure, and GCP but also OpenStack, [IronCore](https://github.com/ironcore-dev/gardener-extension-provider-ironcore), [Hetzner Cloud](https://github.com/23technologies/gardener-extension-provider-hcloud), and others. Like openMCP, Gardener is a Kubernetes extension and "adheres to the same principles for resiliency, manageability, observability, and high automation by design."[^gardener] openMCP can use Gardener as a [cluster provider](concepts/cluster-provider.md). ## Open Component Model @@ -20,7 +23,7 @@ openMCP is a platform built on top of amazing open-source projects. The major on ## Crossplane -"[Crossplane](https://www.crossplane.io/) is an open source, CNCF project built on the foundation of Kubernetes to orchestrate anything."[^crossplane] It makes use of providers to connect to various cloud APIs – a concept that is known from Terraform/OpenTofu. Enabling Crossplane as a [service provider](concepts/service-provider.md) in openMCP allows end-users to make use of the rich ecosystem of Crossplane providers. +"[Crossplane](https://www.crossplane.io/) is an open source, CNCF project built on the foundation of Kubernetes to orchestrate anything."[^crossplane] It makes use of providers to connect to various cloud APIs–a concept that's known from Terraform/OpenTofu. Enabling Crossplane as a [service provider](concepts/service-provider.md) in openMCP allows end-users to make use of the rich ecosystem of Crossplane providers. ## Flux @@ -28,15 +31,17 @@ openMCP is a platform built on top of amazing open-source projects. The major on ## Kyverno -"The [Kyverno](https://kyverno.io/) project provides a comprehensive set of tools to manage the complete Policy-as-Code (PaC) lifecycle for Kubernetes and other cloud native environments."[^kyverno] With Kyverno, both team-internal and organization-wide policies can be defined to establish minimum security standards for managed cloud resources or to represent other corporate standards. +"The [Kyverno](https://kyverno.io/) project provides a comprehensive set of tools to manage the complete Policy-as-Code (PaC) lifecycle for Kubernetes and other cloud native environments."[^kyverno] With Kyverno, you can define team-internal or organization-wide policies to establish minimum security standards for managed cloud resources or to represent other corporate standards. ## External Secrets + "External Secrets Operator is a Kubernetes operator that integrates external secret management systems like AWS Secrets Manager, HashiCorp Vault, [...] and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret."[^externalsecrets] In conjunction with other services like Crossplane and Flux, users can define their landscapes as templates and deploy them without code duplication. The External Secrets Operator can not only import secrets into an MCP but also push secrets generated in the MCP to other systems. + ## Landscaper -"Landscaper provides the means to describe, install and maintain cloud-native landscapes. It allows you to express an order of building blocks, connect output with input data and ultimately, bring your landscape to live."[^landscaper] Operators can activate Landscaper as a service provider in their openMCP environment to ease the rollout of more complex software products for their users. +"Landscaper provides the means to describe, install, and maintain cloud-native landscapes. It allows you to express an order of building blocks, connect output with input data and ultimately, bring your landscape to live."[^landscaper] Operators can activate Landscaper as a service provider in their openMCP environment to ease the roll-out of more complex software products for their users. [^kubernetes]: https://kubernetes.io/ [^gardener]: https://gardener.cloud/ diff --git a/docs/about/project.md b/docs/about/project.md index 2d5082a..9d83521 100644 --- a/docs/about/project.md +++ b/docs/about/project.md @@ -3,29 +3,37 @@ slug: / sidebar_position: 1 --- + + # About openMCP -👋 Welcome to the documentation of openMCP. We are part of [ApeiroRA](https://apeirora.eu/content/projects/) which is an Important Project of Common European Interest - Next Generation Cloud Infrastructures and Services (IPCEI-CIS). +👋 Welcome to the documentation of openMCP. It's part of [ApeiroRA](https://apeirora.eu/content/projects/) which is an Important Project of Common European Interest - Next Generation Cloud Infrastructures and Services (IPCEI-CIS). + ## 🌐 ApeiroRA? + -ApeiroRA is a reference blueprint for an open, flexible, secure, and compliant next-generation cloud-edge continuum and therefore a key contribution to IPCEI-CIS. At a high level, the projects of ApeiroRA allow users to provider-agnostically fetch, request and consume services, and for service providers to describe, offer and provision their services. +ApeiroRA is a reference blueprint for an open, flexible, secure, and compliant next-generation cloud-edge continuum and therefore a key contribution to IPCEI-CIS. At a high level, the projects of ApeiroRA allow users to provider-agnostically fetch, request, and consume services and for service providers to describe, offer, and provision their services. By being open source, ApeiroRA provides a cross-border spillover effect, solidifying the foundation and future of the project. Learn more about ApeiroRA by checking out the official website at [https://apeirora.eu/](https://apeirora.eu/). + ## 🤝 openMCP and ApeiroRA + The Open Managed Control Plane (openMCP) enables extensible Infrastructure- and Configuration-as-Data capabilities as a Service. Based on the Kubernetes Resource Model, all resources in the cloud-edge continuum with ApeiroRA are accessible and managed via a declarative API and corresponding controllers and operators. Together with the controller which understand OCM and declarative deployment orchestrators, consumers can subscribe to a product release-train of software producers and implement an automated, GitOps-driven deployment workflow at the edges. -## 👥 Get Involved +## 👥 Get involved -We welcome contributions of all kinds, from code to documentation, testing, and design. If you're interested in getting involved, check out our [open issues](https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Aopenmcp-project+archived%3Afalse+). + +We welcome contributions of all kinds, from code to documentation, testing, and design. If you're interested in getting involved, check out the [open issues](https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Aopenmcp-project+archived%3Afalse+). + -## 🌈 Code of Conduct +## 🌈 Code of conduct -To facilitate a nice environment for all, check out [our Code of Conduct](https://github.com/openmcp-project/.github/blob/main/CODE_OF_CONDUCT.md). +To facilitate a nice environment for all, check out the [code of conduct](https://github.com/openmcp-project/.github/blob/main/CODE_OF_CONDUCT.md). ## 🪙 Funding diff --git a/docs/developers/getting-started.md b/docs/developers/getting-started.md index bad5562..cadac77 100644 --- a/docs/developers/getting-started.md +++ b/docs/developers/getting-started.md @@ -1 +1,9 @@ -# Getting Started +# Getting started + + + +## Learning resources + +- [Kubebuilder Documentation](https://book.kubebuilder.io/) +- [Operator Pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) +- [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) diff --git a/docs/operators/getting-started.md b/docs/operators/getting-started.md index bad5562..69a5d54 100644 --- a/docs/operators/getting-started.md +++ b/docs/operators/getting-started.md @@ -1 +1 @@ -# Getting Started +# Getting started diff --git a/docs/users/getting-started.md b/docs/users/getting-started.md index bad5562..69a5d54 100644 --- a/docs/users/getting-started.md +++ b/docs/users/getting-started.md @@ -1 +1 @@ -# Getting Started +# Getting started