From a347cb6790a21a056b540e0e8a2a566db7cf9157 Mon Sep 17 00:00:00 2001 From: Laszlo Fogas Date: Fri, 9 Oct 2020 14:26:52 +0200 Subject: [PATCH] Onechart docs spike --- .gitignore | 1 + onechart/templates/configmap.yaml | 2 + website/README.md | 1 + website/docs/examples/cron-job.md | 30 ++++ website/docs/examples/custom-command.md | 25 ++++ .../examples/deploying-a-private-image.md | 30 ++++ website/docs/examples/deploying-an-image.md | 19 +++ website/docs/examples/domain-names.md | 32 ++++ .../docs/examples/environment-variables.md | 31 ++++ website/docs/examples/secrets.md | 31 ++++ website/docs/examples/volumes.md | 46 ++++++ website/docs/getting-started.md | 24 +++ website/docs/index.md | 4 + website/mkdocs.yml | 138 ++++++++++++++++++ website/overrides/home.html | 21 +++ website/overrides/main.html | 2 + 16 files changed, 437 insertions(+) create mode 100644 website/README.md create mode 100644 website/docs/examples/cron-job.md create mode 100644 website/docs/examples/custom-command.md create mode 100644 website/docs/examples/deploying-a-private-image.md create mode 100644 website/docs/examples/deploying-an-image.md create mode 100644 website/docs/examples/domain-names.md create mode 100644 website/docs/examples/environment-variables.md create mode 100644 website/docs/examples/secrets.md create mode 100644 website/docs/examples/volumes.md create mode 100644 website/docs/getting-started.md create mode 100644 website/docs/index.md create mode 100644 website/mkdocs.yml create mode 100644 website/overrides/home.html create mode 100644 website/overrides/main.html diff --git a/.gitignore b/.gitignore index 619e4c8..7017e5a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .idea/ values.yaml manifests +website/site diff --git a/onechart/templates/configmap.yaml b/onechart/templates/configmap.yaml index 072a030..61307bb 100644 --- a/onechart/templates/configmap.yaml +++ b/onechart/templates/configmap.yaml @@ -1,3 +1,4 @@ +{{ if .Values.vars }} apiVersion: v1 kind: ConfigMap metadata: @@ -9,3 +10,4 @@ data: {{- range $key, $val := .Values.vars }} {{ $key }}: {{ $val | quote }} {{- end }} +{{ end }} diff --git a/website/README.md b/website/README.md new file mode 100644 index 0000000..5d9dc02 --- /dev/null +++ b/website/README.md @@ -0,0 +1 @@ +# onechart-docs diff --git a/website/docs/examples/cron-job.md b/website/docs/examples/cron-job.md new file mode 100644 index 0000000..bce6603 --- /dev/null +++ b/website/docs/examples/cron-job.md @@ -0,0 +1,30 @@ +OneChart settings for deploying a cron job: + +```yaml +image: + repository: debian + tag: stable-slim + +schedule: "0 1 0 0 0" +command: | + echo "hello" +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: debian + tag: stable-slim + +schedule: "0 1 0 0 0" +command: | + echo "hello" +EOF + +helm template my-release onechart/cron-job -f values.yaml +``` + +!!! warning + Make sure to use the `onechart/cron-job` chart. diff --git a/website/docs/examples/custom-command.md b/website/docs/examples/custom-command.md new file mode 100644 index 0000000..5f3ea4d --- /dev/null +++ b/website/docs/examples/custom-command.md @@ -0,0 +1,25 @@ +OneChart settings for overriding the default command to run: + +```yaml +image: + repository: debian + tag: stable-slim + +command: | + while true; date; sleep 2; done +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: debian + tag: stable-slim + +command: | + echo "hello" +EOF + +helm template my-release onechart/onechart -f values.yaml +``` diff --git a/website/docs/examples/deploying-a-private-image.md b/website/docs/examples/deploying-a-private-image.md new file mode 100644 index 0000000..915e91c --- /dev/null +++ b/website/docs/examples/deploying-a-private-image.md @@ -0,0 +1,30 @@ +OneChart settings for deploying `my-web-app` image from Amazon ECR: + +```yaml +image: + repository: aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app + tag: x.y.z + +imagePullSecrets: + - name: regcred +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app + tag: x.y.z + +imagePullSecrets: + - name: regcred +EOF + +helm template my-release onechart/onechart -f values.yaml +``` + +!!! warning + The `regcred` image pull credentials must be set up in the cluster. + + See how: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ \ No newline at end of file diff --git a/website/docs/examples/deploying-an-image.md b/website/docs/examples/deploying-an-image.md new file mode 100644 index 0000000..726f7f8 --- /dev/null +++ b/website/docs/examples/deploying-an-image.md @@ -0,0 +1,19 @@ +OneChart settings for deploying the Nginx image: + +```yaml +image: + repository: nginx + tag: 1.19.3 +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: nginx + tag: 1.19.3 +EOF + +helm template my-release onechart/onechart -f values.yaml +``` diff --git a/website/docs/examples/domain-names.md b/website/docs/examples/domain-names.md new file mode 100644 index 0000000..c385bbe --- /dev/null +++ b/website/docs/examples/domain-names.md @@ -0,0 +1,32 @@ +OneChart generates an `Ingress` resource for the Nginx ingress controller with the following settings: + +```yaml +image: + repository: nginx + tag: 1.19.3 + +ingress: + annotations: + kubernetes.io/ingress.class: nginx + host: chart-example.local +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: nginx + tag: 1.19.3 + +ingress: + annotations: + kubernetes.io/ingress.class: nginx + host: chart-example.local +EOF + +helm template my-release onechart/onechart -f values.yaml +``` + +!!! warning + The Nginx ingress controller must be set up in your cluster for this setting to work. diff --git a/website/docs/examples/environment-variables.md b/website/docs/examples/environment-variables.md new file mode 100644 index 0000000..764bb9e --- /dev/null +++ b/website/docs/examples/environment-variables.md @@ -0,0 +1,31 @@ +OneChart settings for setting environment variables: + +```yaml +image: + repository: nginx + tag: 1.19.3 + +vars: + VAR_1: "value 1" + VAR_2: "value 2" +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: nginx + tag: 1.19.3 + + +EOF + +helm template my-release onechart/onechart -f values.yaml +``` + +!!! note + + OneChart creates a `ConfigMap` with all the defined environment variables. + + Then includes all entries with the `EnvFrom` field in the deployment. diff --git a/website/docs/examples/secrets.md b/website/docs/examples/secrets.md new file mode 100644 index 0000000..beccb32 --- /dev/null +++ b/website/docs/examples/secrets.md @@ -0,0 +1,31 @@ +OneChart can reference an existing secret: + +```yaml +image: + repository: nginx + tag: 1.19.3 + +secret: + enabled: true +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: nginx + tag: 1.19.3 + +secret: + enabled: true +EOF + +helm template my-release onechart/onechart -f values.yaml +``` + +!!! note + + OneChart references an existing Kubernetes `Secret` and includes all entries in the deployment with the `EnvFrom` field. + + The secret name must match the release name. `my-release` in the above example. diff --git a/website/docs/examples/volumes.md b/website/docs/examples/volumes.md new file mode 100644 index 0000000..4bd775d --- /dev/null +++ b/website/docs/examples/volumes.md @@ -0,0 +1,46 @@ +OneChart settings for setting environment variables: + +```yaml +image: + repository: nginx + tag: 1.19.3 + +volumes: + - name: data + path: /var/lib/1clickinfra/data + size: 10Gi + storageClass: default +``` + +Check the Kubernetes manifest: + +```bash +cat << EOF > values.yaml +image: + repository: nginx + tag: 1.19.3 + +volumes: + - name: data + path: /var/lib/1clickinfra/data + size: 10Gi + storageClass: default +EOF + +helm template my-release onechart/onechart -f values.yaml +``` + +!!! warning + + OneChart generates a `PeristentVolumeClaim` with this configuration and mounts it to the given path. + + You have to know what `storageClass` is supported in your cluster. + + - On Google Cloud, `standard` gets you disk + - On Azure, `default` gets you a normal block storage + - Amazon EKS, `TODO` + - Use `do-block-storage` for Digital Ocean + +### Mount an Azure file storage + +TODO diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md new file mode 100644 index 0000000..5853aff --- /dev/null +++ b/website/docs/getting-started.md @@ -0,0 +1,24 @@ + +Add the OneChart Helm repository: + +```bash +helm repo add onechart https://chart.onechart.dev +``` + +Check the generated Kubernetes yaml: + +```bash +helm template my-release onechart/onechart \ + --set image.repository=nginx \ + --set image.tag=1.19.3 +``` + +Deploy with Helm: + +```bash +helm install my-release onechart/onechart \ + --set image.repository=nginx \ + --set image.tag=1.19.3 +``` + +See all [Examples](/examples/deploying-an-image) diff --git a/website/docs/index.md b/website/docs/index.md new file mode 100644 index 0000000..e872fbe --- /dev/null +++ b/website/docs/index.md @@ -0,0 +1,4 @@ +--- +template: home.html +title: Material for MkDocs +--- diff --git a/website/mkdocs.yml b/website/mkdocs.yml new file mode 100644 index 0000000..ad842a1 --- /dev/null +++ b/website/mkdocs.yml @@ -0,0 +1,138 @@ +# Copyright (c) 2016-2020 Martin Donath +# Copyright (c) 2020 Laszlo Fogas + +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to +# deal in the Software without restriction, including without limitation the +# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +# sell copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: + +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. + +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. + +# Project information +site_name: OneChart +site_url: https://onechart.dev +site_author: Laszlo Fogas +site_description: >- + One Helm chart to rule them all. One Helm chart for your apps. + Because no-one can remember the Kubernetes yaml syntax. +# Repository +repo_name: onechart/onechart +repo_url: https://github.com/onechart/onechart +edit_uri: https://github.com/onechart/onechart/website + +# Copyright +copyright: Copyright © 2020 Laszlo Fogas + +# Configuration +theme: + name: material + custom_dir: overrides + + # 404 page + static_templates: + - 404.html + + # Don't include MkDocs' JavaScript + include_search_page: false + search_index_only: true + + # Default values, taken from mkdocs_theme.yml + language: en + features: + - navigation.tabs + - navigation.instant + palette: + scheme: default + primary: indigo + accent: indigo + font: + text: Roboto + code: Roboto Mono + favicon: assets/favicon.png + icon: + logo: logo + +# Plugins +plugins: + - search + - minify: + minify_html: true + +# Customization +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/laszlocph + - icon: fontawesome/brands/gitter + link: https://gitter.im/squidfunk/mkdocs-material + - icon: fontawesome/brands/twitter + link: https://twitter.com/laszlocph + - icon: fontawesome/brands/linkedin + link: https://linkedin.com/in/laszlofogas + +# Extensions +markdown_extensions: + - admonition + - abbr + - attr_list + - def_list + - footnotes + - meta + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets: + check_paths: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +# Page tree +nav: + - Home: index.md + - Getting started: + - Getting started: getting-started.md + - Examples: + - Deploying an image: examples/deploying-an-image.md + - Deploying a private image: examples/deploying-a-private-image.md + - Environment variables: examples/environment-variables.md + - Secrets: examples/secrets.md + - Domain names: examples/domain-names.md + - Volumes: examples/volumes.md + - Custom command: examples/custom-command.md + - Cron job: examples/cron-job.md diff --git a/website/overrides/home.html b/website/overrides/home.html new file mode 100644 index 0000000..dc4fcda --- /dev/null +++ b/website/overrides/home.html @@ -0,0 +1,21 @@ +{% extends "main.html" %} +{% block extrahead %} + +{% endblock %} + +{% block tabs %} +{{ super() }} +
+
+
+
+

Technical documentation that just works

+

{{ config.site_description }}

+
+
+
+
+{% endblock %} +{% block site_nav %}{% endblock %} +{% block content %}{% endblock %} +{% block footer %}{% endblock %} \ No newline at end of file diff --git a/website/overrides/main.html b/website/overrides/main.html new file mode 100644 index 0000000..5cb6467 --- /dev/null +++ b/website/overrides/main.html @@ -0,0 +1,2 @@ +{% extends "base.html" %} +