CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# CONTRIBUTING
+
+This repository hosts lasting documents for the OpenGitOps project, which are versioned and released together.
+
+In addition to contributions to the ongoing evolution of the GitOps [Principles](hhttps://github.com/open-gitops/documents/blob/v1.0.0/PRINCIPLES.md) and [Glossary](https://github.com/open-gitops/documents/blob/v1.0.0/GLOSSARY.md), OpenGitOps project is looking for additional types of content to help new and existing GitOps practitioners learn from each other on their journey.
+
+These may include content initially envisioned in the [Work Products](https://github.com/cncf/tag-app-delivery/blob/main/gitops-wg/charter.md#work-products-wip) section of GitOps Working Group charter: methodologies and approaches documents, a GitOps landscape document, or working examples for getting started.
+Other content, such as white papers, case studies, architectural patterns, tool and technology comparisons, or tutorials, are also good candidates for inclusion.
+Use your imagination!
+
+It's encouraged to first discuss any ideas or questions asynchronously with the GitOps community using [OpenGitOps project discussions](https://github.com/open-gitops/project/discussions). 
+These discussion topics are regularly highlighted in the twice-monthly community meetings, and in some cases, special teams are formed within OpenGitOps to collaborate on specific content topics raised in these discussions.
+
+However it's created, all content in this repo must meet the acceptance criteria below to be considered for inclusion.
+Pull requests must also receive at least two approvals from project maintainers.
+We look forward to your contributions!
+
+## Minimum Acceptance Criteria:
+
+* Copyright is assigned to OpenGitops / CNCF project
+* Content is not a duplicate (for version changes in technology, submit a new version of an existing article)
+* Content is informational and not promotional, Tutorials and case studies of vendor technology are allowed, but promotional content is limited to 1 line and 1 link (excluding any links to free trials in the requirements section) at the start or end of the content
+* Content should not contain branding for anything other than the OpenGitops project
+* Content must be in markdown format
+

GLOSSARY.md

@@ -18,6 +18,13 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su
 - ## Drift
 
     When a system's actual state has moved or is in the process of moving away from the [desired state](#desired-state), this is often referred to as drift.
+
+- ## Pull
+
+    [Principle 3](./PRINCIPLES.md) (Pulled Automatically) specifies the desired state must be "pulled" rather than "pushed", primarily because the software agents must be able to access the [desired state](#desired-state) from the [state store](#state-store) at _any_ time, not only when there is an intentional change in the state store triggering a push event.
+    This is a prerequisite for [reconciliation](#reconciliation) to happen [continuously](#continuous), as specified in [principle 4](./PRINCIPLES.md) (Continuously Reconciled).
+    Note that – in contrast to traditional CI/CD, where automation is generally driven by pre-set triggers – in GitOps, [reconciliation](#reconciliation) is triggered _whenever_ there is a divergence.
+    Divergence could be due to the actual state unintentionally [drifting](#drift) from the desired state declarations – not only due to a new desired state declaration version having been changed intentionally.
 
 - ## Reconciliation
 

PRINCIPLES.md

@@ -5,19 +5,18 @@ These principles are derived from modern software operations, but are also roote
 
 The [desired state](./GLOSSARY.md#desired-state) of a GitOps managed system must be:
 
-1. **Declarative**
+1. ## Declarative
 
     A [system](./GLOSSARY.md#software-system) managed by GitOps must have its desired state expressed [declaratively](./GLOSSARY.md#declarative-description).
 
-2. **Versioned and Immutable**
+2. ## Versioned and Immutable
 
     Desired state is [stored](./GLOSSARY.md#state-store) in a way that enforces immutability, versioning and retains a complete version history.
 
-3. **Pulled Automatically**
+3. ## Pulled Automatically
 
-    Software agents automatically pull the desired state declarations from the source.
+    Software agents automatically [pull](./GLOSSARY.md#pull) the desired state declarations from the source.
 
-4. **Continuously Reconciled**
+4. ## Continuously Reconciled
 
     Software agents [continuously](./GLOSSARY.md#continuous) observe actual system state and [attempt to apply](./GLOSSARY.md#reconciliation) the desired state.
-

README.md

@@ -14,16 +14,37 @@ See the [releases](https://github.com/open-gitops/documents/releases) page for p
 Note the difference between pre-releases and full releases, defined by the [Semantic Versioning](https://semver.org/) scheme followed by this repo.
 See [open milestones](https://github.com/open-gitops/documents/milestones) for planned future releases.
 
-## About OpenGitOps
-
-OpenGitOps is a [CNCF Sandbox project](https://www.cncf.io/sandbox-projects/) for lasting programs, documents and code from the [GitOps Working Group](https://github.com/gitops-working-group/gitops-working-group).
+Please find translations of the principles as well as the glossary in the [i18n](./i18n/) folder.
 
-## About the GitOps Working Group
+## About OpenGitOps
 
-The GitOps Working Group is a WG under the [CNCF App Delivery TAG](https://github.com/cncf/tag-app-delivery), with a focus to clearly define a vendor-neutral, principle-led meaning of GitOps. This will establish a foundation for interoperability between tools, conformance, and certification.
-It is an open public working group welcoming anyone who would like to join and help.
-See [How to Get Involved](https://github.com/gitops-working-group/gitops-working-group/blob/main/README.md#how-to-get-involved).
+For more information about the OpenGitOps project, see: <https://github.com/open-gitops/project>
 
 ## Code of Conduct
 
 The OpenGitOps community follows the [CNCF Code of Conduct](https://github.com/open-gitops/.github/blob/main/CODE_OF_CONDUCT.md).
+
+## Reference this Content
+
+Below is a [BibTex](https://www.bibtex.org) code snippet to use as reference for the content available in this repository. There is one required change, and several optional adjustments you may make to the snippet.
+
+Required:
+- at minimum you will need to change the `Accessed` date (when you accessed this material) in the [note](https://www.bibtex.com/f/note-field/) field.
+
+Optional: You may choose to reference a different release version. If so:
+- Change the `Release version` in the [note](https://www.bibtex.com/f/note-field/) field.
+- Update the [year](https://www.bibtex.com/f/year-field/) field to match. See list of releases by date [here](https://github.com/open-gitops/documents/releases).
+- Update the file link in `Authors` in the [note](https://www.bibtex.com/f/note-field/) field. You may find the list of authors by your chosen release version in the [reference](https://github.com/open-gitops/documents/blob/main/reference/) directory in this Git repo.
+
+Optional: You may reference multiple versions in the same article. If so:
+- Update the [CiteKey](https://www.bibtex.com/g/bibtex-format/#citekey) below ("GitOps-Principles-and-Glossary") so each is unique (for example, append the version "-v1.0.0").
+- ⚠️ Note that the GitOps Principles and Glossary are versioned together, so when citing an individual principle and glossary item, ensure the versions match. This is because the two files have hyperlinks from one to the other that may be incorrect or broken between different versions.
+
+```
+@misc{GitOps-Principles-and-Glossary,
+  title        = {{GitOps Principles and Glossary}},
+  howpublished = {\url{https://github.com/open-gitops/documents}},
+  note         = {Accessed: YYYY-MM-DD. Release version: 1.0.0. Authors: \url{https://github.com/open-gitops/documents/blob/main/reference/authors-v1.0.0.md}.},
+  year         = {2021}
+}
+```

i18n/GLOSSARY_de.md

@@ -0,0 +1,57 @@
+## GitOps-Glossar {{version}}
+
+Dieses Glossar begleitet die [GitOps-Prinzipien](./PRINCIPLES_de.md) und andere Dokumente dieses Repositorys.
+
+- ## Kontinuierlich
+
+    Mit "kontinuierlich" ist im Kontext der [Angleichung](#angleichung) gemeint, dass diese regelmäßig, aber nicht zwangsweise sofort erfolgt.
+
+- ## Deklarative Beschreibung
+
+    Eine Konfiguration, die den gewünschten [Soll-Zustand](#soll-zustand) eines Systems beschreibt, ohne Vorgehensweisen zu definieren wie dieser erreicht wird.
+    Dies erzielt die Trennung der Konfiguration (Soll-Zustand) von der Implementierung (Befehle, API-Aufrufe, Skripte usw.), die verwendet wird, um den gewünschten Zustand zu erreichen.
+
+- ## Soll-Zustand
+
+    Die Gesamtheit aller Konfigurationen, die es braucht, um ein sich gleichverhaltendes System wiederherzustellen.
+    Diese Konfigurationen enthalten im Allgemeinen keine gespeicherten Anwendungsdaten wie z.B. Datenbankinhalte, wohl aber die entsprechenden Zugangsdaten für den Zugriff darauf oder Einstellungen für Wiederherstellungs-Tools des Systems.
+
+- ## Abweichung
+
+    Abweichung bezeichnet eine (beginnende) Entfernung des Ist-Zustandes eines Systems vom gewünschten [Soll-Zustand](#soll-zustand).
+
+- ## Beziehen der Änderungen (Pull)
+
+
+    [Prinzip 3](./PRINCIPLES_de.md) (Automatisch bezogen) spezifiziert, dass der gewünschte Zustand "gezogen" (Pull) statt von außen "gedrückt" (Push), werden muss, hauptsächlich weil die Software-Agenten in der Lage sein müssen, den gewünschten Zustand aus dem Zustandsspeicher zu jeder Zeit abzurufen – nicht nur dann, wenn es eine absichtliche Änderung im Zustandsspeicher gibt, die ein Push-Ereignis auslöst.
+    Dies ist eine Voraussetzung dafür, dass die [Angleichung](#Angleichung) [kontinuierlich](#kontinuierlich) erfolgen kann, wie in [Prinzip 4](./PRINCIPLES_de.md) (Kontinuierlich angeglichen) spezifiziert.
+    Beachte, dass – im Gegensatz zu traditionellem CI/CD, bei dem Automatisierung in der Regel durch vordefinierte Auslöser gesteuert wird – im GitOps die [Angleichung](#Angleichung) _immer_ dann ausgelöst wird, wenn eine Abweichung vorliegt.
+    Eine [Abweichung](#Abweichung) könnte dadurch entstehen, dass sich der tatsächliche Zustand unbeabsichtigt vom erklärten [Soll-Zustand](#Soll-Zustand) entfernt – nicht nur aufgrund einer neuen Version des gewünschten Soll-Zustands, die absichtlich geändert wurde.
+
+- ## Angleichung
+
+    Der Prozess, bei dem sichergestellt wird, dass der tatsächliche Zustand eines Systems mit seinem [Soll-Zustand](#soll-zustand) übereinstimmt.
+    Im Gegensatz zur traditionellen CI/CD, bei der die Automatisierung im Allgemeinen durch voreingestellte Auslöser gesteuert wird, wird bei GitOps die Angleichung immer dann ausgelöst, wenn eine Abweichung vorliegt.
+    Die [Abweichung](#abweichung) kann darauf zurückzuführen sein, dass sich der Ist-Zustand unbeabsichtigt geändert hat oder dass eine neue Version der Soll-Zustands-Beschreibung vorliegt.
+    Auf der Grundlage von Richtlinien und [Feedback](#feedback) des Systems sowie früherer Angleichungsversuche werden Maßnahmen ergriffen, um die Abweichung im Laufe der Zeit zu verringern.
+
+- ## Softwaresystem
+
+    Ein mittels GitOps verwaltetes Softwaresystem beinhaltet:
+
+    1. Eine oder mehrere Laufzeitumgebungen, die aus verwalteten Ressourcen bestehen
+    1. Verwaltungs-Agenten innerhalb jeder einzelnen Laufzeitumgebung
+    1. Richtlinien zur Steuerung des Zugriffs sowie der Verwaltung der Repositorys, Deployments und Laufzeitumgebungen
+
+- ## Zustandsspeicher
+
+    Ein System, um unveränderliche Versionen der Beschreibung des [Soll-Zustand](#soll-zustand) zu speichern.
+    Dieser Speicher sollte Zugriffssteuerung und Audits der Änderungen des Soll-Zustands unterstützen.
+    Git, von dem sich der Name GitOps ableitet, ist das kanonische Beispiel für diesen Speicher, aber jedes System das die genannten Bedingungen erfüllt, kann benutzt werden.
+    In jedem Fall muss der Speicher ordnungsgemäß konfiguriert sein und Maßnahmen getroffen werden, um den Anforderungen der GitOps-Prinzipien gerecht zu werden.
+
+- ## Feedback
+
+    GitOps folgt der [Kontrolltheorie](https://de.wikipedia.org/wiki/Kontrolltheorie) und wird in einem geschlossenen Kreislauf betrieben.
+    In der Kontrolltheorie beschreibt die Rückmeldung, wie frühere Versuche, einen [Soll-Zustand](#soll-zustand) anzuwenden, den tatsächlichen Zustand beeinflusst haben.
+    Verlangt beispielsweise der Soll-Zustand mehr Ressourcen als in einem System vorhanden sind, könnte der Software-Agent versuchen, automatisch zu einer vorherigen Version zurückzurollen oder menschlichen Betreibern einen Alarm senden.

i18n/GLOSSARY_es.md

@@ -0,0 +1,48 @@
+# Glosario de GitOps {{version}}
+
+Este glosario acompaña a los [Principios de GitOps](./PRINCIPLES_es.md), y otros documentos de apoyo en este repositorio.
+
+- ## Continuo
+
+    "Continuo" pretende coincidir con el término estándar de la industria: [reconciliación](#reconciliación) continua, pero que no sea necesariamente instantánea.
+
+- ## Descripción Declarativa
+
+    Una configuración que describe el estado de funcionamiento deseado de un sistema sin especificar los procedimientos de cómo se alcanzará ese estado. Esto separa la configuración (descripción del estado deseado) de la implementación (comandos, llamadas a la API, scripts, etc) utilizados para lograr ese estado.
+
+- ## Estado deseado
+
+    El conjunto de todos los datos de configuración que son suficientes para recrear el sistema de manera en que las instancias de un sistema sean indistinguibles en su comportamiento.
+    Estos datos de configuración generalmente no incluyen los datos persistentes de la aplicación, por ejemplo, el contenido de la base de datos, aunque a menudo incluye las credenciales para acceder a esos datos, o la configuración de las herramientas de recuperación de datos que se ejecutan en ese sistema.
+
+- ## Desvío
+
+    Cuando el estado actual de un sistema se ha alejado o está en proceso de alejarse del [estado deseado](#estado-deseado), ésto se suele denominar, desvío.
+
+- ## Pull
+    [Principio 3] especifica el estado deseado debe ser pull (descargar) en vez de pushed (subir), primariamente debido a que los agentes de software deben en cualquier momento ser capaces de acceder al estado deseado desde el almacén de datos, no solamente cuando haya un cambio intencional en el almacén de datos que se pueda invocar un evento de push. Este es un prerrequisito en el principio 4. Note que en contraste con la IC/DC tradicional, donde la automatización es generalmente manejada por una invocación (trigger) predefinida, en GitOps, la reconciliación será invocada cuando haya una divergencia. La divergencia puede darse sobre el estado actual intencionalmente en las declaraciones del estado deseado, no solamente debido a una nueva versión de declaración de estado deseado que haya sido cambiado intencionalmente.
+
+- ## Reconciliación
+
+    El proceso de asegurar que el estado actual de un sistema coincide con su [estado deseado](#estado-deseado).
+    Contrario al IC/DC tradicional, en el que la automatización generalmente es manejada por los activadores (triggers) preestablecidos, en GitOps la reconciliación se activa siempre que haya una divergencia. La divergencia puede darse al estado actual intencional de [desvio] (#desvio) de las declaraciones del estado deseado, no solamente debido a una nueva versión de declaración de estado deseado que haya sido cambiado intencionalmente. Se toman acciones basadas en las políticas entorno a la reconciliación [feedback](#Reconciliación) del sistema e intentos previos de reconciliación, con el fin de reducir la desviación en el tiempo.
+
+- ## Sistema de software
+
+    Un sistema de software manejado por GitOps incluye:
+
+    1. Uno o más entornos de ejecución compuestos por recursos gestionados
+    1. Los agentes de gestión dentro de cada tiempo de ejecución
+    1. Políticas de control de acceso y manejo de repositorios, despliegues, tiempos de ejecución
+
+- ## Almacenamiento del estado
+
+    Un sistema para almacenar versiones inmutables de las declaraciones de [estado deseado](#estado-deseado).
+    Este almacén de estado debe proporcionar control de acceso y auditoría sobre los cambios en la definición del Estado Deseado.
+    Git, del que GitOps deriva su nombre, es el ejemplo canónico utilizado como almacén de estado, pero se puede utilizar en cualquier otro sistema que cumpla estos criterios.
+    En todos los casos, los almacenes de estado deben ser correctamente configurados y deben tomar precauciones para cumplir con los requerimientos establecidos en los Principios de GitOps.
+
+- ## Realimentación
+
+    Open GitOps sigue la [teoría del control](https://es.wikipedia.org/wiki/Teor%C3%ADa_del_control) y funciona en un bucle cerrado. En la teoría del control, la realimentación representa cómo los intentos previos de aplicar un estado deseado han afectado el estado actual. Por ejemplo, si el estado deseado requiere más recursos de los que existen en un sistema, el agente de software puede intentar añadir recursos, retroceder automáticamente a una versión anterior o enviar alertas a los operadores humanos.
+