Merge branch '965-document-apis' into 'master'

add documentation about the available APIs

Closes #965

See merge request openappstack/openappstack!574

docs/_static/diagrams/apis.svg

+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than diagrams.net -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="801px" height="341px" viewBox="-0.5 -0.5 801 341" content="&lt;mxfile host=&quot;app.diagrams.net&quot; modified=&quot;2021-10-28T10:00:21.666Z&quot; agent=&quot;5.0 (X11)&quot; version=&quot;15.5.2&quot; etag=&quot;OYfaiNPuFCJlRQW4tJ_b&quot;&gt;&lt;diagram id=&quot;QBf3Kggn1ttFnsHP0EVe&quot; name=&quot;Page-1&quot;&gt;5VnbcuI4EP0aHpPyBQN55DKZUKlsUqFmd18VWxjtyJZXkrnM12/L94swJgPU1M5LYh/L3XL36dOSGNjzYP+Vo2jzwjxMB5bh7Qf2YmBZpulM4J9CDikytp0U8DnxskElsCI/cAYaGRoTD4vaQMkYlSSqgy4LQ+zKGoY4Z7v6sDWjda8R8nELWLmIttG/iCc3KTpxjBJ/wsTf5J5NI3sSoHxwBogN8tiuAtlfBvacMybTq2A/x1QFL49L+t7jkafFxDgOZZ8Xom9//L163RrjIZ5I4+Xb3v3n6S6zskU0zj74lR8AeOZIMgEX07dlNn15yGMidiSgKIS7WXsSuUXMJd5XoGxSXzELsEx8ZE9HWXwygth55ndluK08qJtKqAsQZSn2C9OFt3egBAp9mHjhzj7t7kHnza47Q1RiHiKJZywOPVGNPFxUvrOEknyckZthKzcDa0RhPjOPbNVUKPHD5MHo31ixaEbxWpZ3cOVn/5O3YtpEKMmRN1UGUKVYuJxEkrAQvnOaj4Ppl0MrYNtiH6RtKvmeOiQiFOYYZT4JK26rzyqwxop24p3+l4lIcB8iCDV8SMgtxI5x79KeXh6nlzZ5f38PE8bSvf+EZW0+O929cbYmSW0BgoIIoPSvIqfrQmEkQUQhkCtQAnHhz50WPjh2GSjOQceeyxFHG6Hm+w2tBBFU+EYGUPsLU4UoK9ukWO2ZEkoC/WaawQHxPPXyjGNBfqCPxJAB9xEjoUzUx5kNnIWyFINGpx1TGRaSs+94zijjgIQsEWhIEG1AnEmkKjyzewEJHzY0dei0JdzSiKo57JDwmpyeq52jI33t6eBxdLqt5TlyISaYXyZI1vh05zF1Ufpko+vjb/xrdLrx0U7XpUivy8VcJYWzLawR+Tml27tICwLcvkzblOtkem8e3lkNXmhoaGt44VyrViet7D/HH0A5LHGPFeg1SnVonC6d4VATI7tL0I6Xah9/emm4fa0+tLL1J6aYs5/MUSczeifObMSx3YdMRxfGiXMlbucTuskifobc73cxbIwvsGz/n6x1ehLt4VyiNUXU1DDNvKWImu2d/CON979GVTZXIprloXYlcr2ytI5Ey3iOhWQBkDFZIV8heubZ3ei0qBVnKLXoXY9r9rHoPWEavEM7QAJfJXbWT8Zu3O6rlq4hmJOrxc65YUOYRhEFvU2pbCxDIRGl2W2vTfc7RmoVYcxZuCb+C1K9RR2PqHlG0SA5doUHMT/H6ApLZSaOknKrrPQCFJI1FjJ3cuIAquvLl6EPPaW7E5bIAkeUHdIjCkPl1zJWsEfG65gKLHsaeWNeX38rzLfExX2HNw50+h9M/EYdvNCkT7dwS6MNuq5kjq6mDcdPfLu4voo/hCQyTotIwGRUYVJoZOWm+INrz9F6q80dRAUnU+NEZVkcI9RvuQc/vy/1IJ+p+xniE9yD2/JHpnQXWP5UZ3/5Dw==&lt;/diagram&gt;&lt;/mxfile&gt;"><defs/><g><path d="M 20 23 L 20 0 L 220 0 L 220 23" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 20 23 L 20 200 L 220 200 L 220 23" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 20 23 L 220 23" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="119.5" y="16">Ory Kratos API</text></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 105px; margin-left: 2px;"><div style="box-sizing: border-box; font-size: 0px; text-align: left;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: nowrap;"><div align="left"><ul><li>Page descriptions:</li></ul><ul><ul><li><div><span>login</span></div></li><li><div>I forgot my password</div></li><li><div>MFA</div></li><li><div>... etc.</div></li></ul><li><div>Profile &amp; account management</div></li><li><div>Account recovery<span></span></div></li></ul></div></div></div></div></foreignObject><text x="2" y="109" fill="#000000" font-family="Helvetica" font-size="12px">Page descriptions:...</text></switch></g><path d="M 230 23 L 230 0 L 350 0 L 350 23" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 230 23 L 230 200 L 350 200 L 350 23" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 230 23 L 350 23" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="289.5" y="16">Ory Hydra API</text></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 55px; margin-left: 275px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: nowrap;"><ul><li>OIDC provider</li></ul></div></div></div></foreignObject><text x="275" y="59" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">OIDC provider</text></switch></g><path d="M 360 23 L 360 0 L 800 0 L 800 23" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 360 23 L 360 340 L 800 340 L 800 23" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 360 23 L 800 23" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="579.5" y="16">Kubernetes API</text></g><path d="M 370 58 L 370 35 L 520 35 L 520 58" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 370 58 L 370 320 L 520 320 L 520 58" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 370 58 L 520 58" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="444.5" y="51">Velero</text></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 75px; margin-left: 352px;"><div style="box-sizing: border-box; font-size: 0px; text-align: left;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: nowrap;"><div align="left"><ul><li>Back-ups</li></ul><ul></ul></div></div></div></div></foreignObject><text x="352" y="79" fill="#000000" font-family="Helvetica" font-size="12px">Back-ups&#xa;</text></switch></g><path d="M 530 58 L 530 35 L 800 35 L 800 58" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 530 58 L 530 320 L 800 320 L 800 58" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 530 58 L 800 58" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="664.5" y="51">Flux</text></g><path d="M 540 93 L 540 70 L 800 70 L 800 93" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 540 93 L 540 320 L 800 320 L 800 93" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 540 93 L 800 93" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="669.5" y="86">Flux Kustomization</text></g><path d="M 550 163 L 550 140 L 800 140 L 800 163" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 550 163 L 550 320 L 800 320 L 800 163" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 550 163 L 800 163" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="674.5" y="156">Flux HelmRelease</text></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 240px; margin-left: 532px;"><div style="box-sizing: border-box; font-size: 0px; text-align: left;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: nowrap;"><div align="left"><ul><li>Application Installation</li><li>Reads ConfigMaps for app configuration</li><li>Sets up Kubernetes manifests for:</li><ul><li>Ingress</li><li>Deployment / Statefulset</li><li>Pods</li><li>Services</li><li>etc.</li></ul></ul></div></div></div></div></foreignObject><text x="532" y="244" fill="#000000" font-family="Helvetica" font-size="12px">Application InstallationReads ConfigMaps for...</text></switch></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 120px; margin-left: 615px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: nowrap;"><ul><li>Substitutes some cluster<br /><div align="left">-wide variables</div></li></ul></div></div></div></foreignObject><text x="615" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Substitutes some cluster...</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>

docs/design.md

@@ -120,3 +120,29 @@ are pushd the branch that Flux tracks, the changes are applied to the cluster.
 We use Flux 2 in "read only" mode, which means that your OpenAppStack cluster
 does not push changes to our Git repository. You can read more about Flux 2 and
 its components in the [flux 2 documentation](https://fluxcd.io/docs).
+
+## APIs
+
+OpenAppStack includes several APIs that are available for some pieces of the
+software to talk to. Specifically the [Dashboard
+application](https://open.greenhost.net/openappstack/admin-frontend) uses most
+of these APIs.
+
+<!-- Edit URL:
+https://viewer.diagrams.net/?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1#R5VnbcqM4EP0aPybFxbc8%2BjKZuFLZpOKa3X1VQMbaEYiVhC%2Fz9dsCcTHIGGds19TOSwIH0S26T5%2BW5J47C3dfOYrXL8zHtOdY%2Fq7nznuOY9uDMfxTyD5DRiMNBJz4elAJLMkPrEFLownxsTgYKBmjksSHoMeiCHvyAEOcs%2B3hsBWjh15jFOAGsPQQbaJ%2FEV%2BuM3Q8sEr8CZNgnXu2Lf0kRPlgDYg18tm2Arlfeu6MMyazq3A3w1QFL49L9t7jkafFxDiOZJcX4m9%2F%2FL183VijPh5L6%2BXbzvvn6U5b2SCa6A9%2B5XsAnjmSTMDF5G2hpy%2F3eUzEloQURXA3bU4it4i5xLsKpCf1FbMQy9SHfjrU8dEEcfPMb8twO3lQ15VQFyDSKQ4K04W3d6AEigKYeOHOPe3uweTNPXSGqMQ8QhJPWRL5ohp5uKh8Zwml%2BTgjN%2F1GbnrOkMJ8pj7ZqKlQEkTpg%2BG%2FiWLRlOKVLO%2FgKtD%2F07cSWkcoyZE3VQZQpVh4nMSSsAi%2Bc5KPg%2BmXQytg02IXpGkq%2FZ5DSMQoyjHKAhJV3FafVWCDFePEW%2F0vUpHgAUQQanifkluILeP%2BpT29PE4ubfL%2B%2Fh4mjKV3%2FwnLxny2unvjbEXS2gIEhTFA2V9FTs%2BDwkiDiCIgV6gE4sKfOyl8cOwxUJy9iT2XI44xQvX3a1oJIqjwtQyh9ue2CpEu27RY3akSSgL9ZqLhkPi%2BennKsSA%2F0EdqyIL7mJFIpuozmPYGc2UpAY3OOqYyLCRn3%2FGMUcYBiVgq0JAgWoM4k0hVuLZ7AQnv1zS1P2hKuGMQVbvfIuEHcnqudg6P9LWnvc%2FR6baW58iDmGB%2BmSA5o9OdxzZF6ZONrou%2F0a%2FR6UZHO12bIr0u5jOVFM42sEbk55Ru5yItCHD7Mm1SrpXpnXl459R4YaCha%2BDF4Fq1Om5k%2Fzn5AMphiTusQK9Rqn3rdOn0%2B4YYuW2CdrxUu%2FgzS8Pta%2FWhka0%2FMcWc%2FWSOWpnROXF2LY7NPmQPTGEcD67E7XxCN1nET5H3%2FS6BjfEFlu3%2Fk7VOR6I9nEu0uojaBqbZtxRRu7mTf6TJ7teoyvpKxLA8NK5ErleWzpFoWc%2BJkCwEMqYr5CtEzz67G50WteIM5SB61%2BOaeyx6T5iG79AOkMBXiZ3zk7EbNfuqY2oI9vhqsRvcsCFM4piC3mZUthaRkIhSfdtp0%2F2OkVpFWDMWrUjwglRvUccjap5x3EuPXeFBws8xusRSmUnitNwqK70QRWSFhcydnDiAavvyRRRAT2nvhCUyxzFl%2B%2ByIwlL5dawl7JHxKqECy45G3pjf1d8S8w3xcNfhtQOd7gcTv1EHLzTp0y3cMWiDqSvZw6tpw%2FET3zauL5MPIYlMsiISMBlVmBQaWbkp%2FuDGc7TOanMHUcHp1DhRWRbHCPVb7sHP70sdyGebfob4BPfgtvyRKdsFlj%2FVuV%2F%2BAw%3D%3D -->
+![API graph](_static/diagrams/apis.svg)
+
+- [Ory Kratos](https://www.ory.sh/kratos/docs/quickstart/) is the user
+  management API that we use. It comes with several handy features, like sending
+  password reset emails and (soon) MFA.
+- [Ory Hydra](https://www.ory.sh/hydra/docs/) provides us with an OpenID Connect
+  workflow.
+- [Velero](https://velero.io/docs/v1.7/) is a backup mechanism that integrates
+  well with Kubernetes: it includes "Custom Resource Definitions" for
+  backups and backup locations. As such, we can access it through the Kubernetes
+  API.
+- [Flux 2](https://fluxcd.io/docs/) is used to configure and auto-update
+  applications. App configuration happens mostly through Kubernetes `ConfigMaps`
+  and `Secrets` and are applied through the Flux CRDs
+  [`Kustomization`](https://fluxcd.io/docs/components/kustomize/kustomization/)
+  and [`HelmRelease`](https://fluxcd.io/docs/components/helm/helmreleases/).