From f3a3e97618c06e7298bb88b0e766914606500b86 Mon Sep 17 00:00:00 2001 From: Ilir Bekteshi Date: Tue, 10 Mar 2020 11:10:51 +0100 Subject: [PATCH] Init mkdocs and gh workflow for publishing docs Initialize mkdocs for serving documentation on GitHub pages On push to ms-3 branch a workflow publishes the documentation to gh-pages which gets served by GitHub The content is based on README.md --- .github/workflows/mkdocs.yml | 21 +++++++++ MKDOCS.md | 23 ++++++++++ docs/air_gap.md | 0 docs/concepts.md | 83 ++++++++++++++++++++++++++++++++++++ docs/getting_started.md | 30 +++++++++++++ docs/index.md | 19 +++++++++ mkdocs.yml | 18 ++++++++ 7 files changed, 194 insertions(+) create mode 100644 .github/workflows/mkdocs.yml create mode 100644 MKDOCS.md create mode 100644 docs/air_gap.md create mode 100644 docs/concepts.md create mode 100644 docs/getting_started.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000..e3d6d77 --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,21 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: + - ms-3 + paths: + - docs/ + - mkdocs.yml + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout master + uses: actions/checkout@v1 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@1.11 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/MKDOCS.md b/MKDOCS.md new file mode 100644 index 0000000..f57978b --- /dev/null +++ b/MKDOCS.md @@ -0,0 +1,23 @@ +# Qlik Sense installer documentation + +## Local development of documentation + +Documentation is built using [mkdocs](https://www.mkdocs.org/) and uses [Material for MKDocs theme](https://squidfunk.github.io/mkdocs-material/) + +Requirements: Python and PIP or Docker + +```console +pip install mkdocs +pip install mkdocs-material +``` + +View live changes locally at http://localhost:8000 +```console +mkdocs serve +``` + +### Docker + +```console +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material +``` diff --git a/docs/air_gap.md b/docs/air_gap.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000..00175cc --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,83 @@ +# How qliksense cli works + +At the initialization `qliksense` cli create few files in the director `~/.qliksene` and it contains following files + +```console +.qliksense +├── config.yaml +├── contexts +│   └── qlik-default +│   └── qlik-default.yaml +└── ejson + └── keys +``` + +`qlik-default.yaml` is a default CR has been created with some default values like this + +```yaml +apiVersion: qlik.com/v1 +kind: Qliksense +metadata: + name: qlik-default +spec: + profile: docker-desktop + secrets: + qliksense: + - name: mongoDbUri + value: mongodb://qlik-default-mongodb:27017/qliksense?ssl=false + rotateKeys: "yes" + releaseName: qlik-default +``` + +The `qliksense` cli creates a default qliksense context (different from kubectl context) named `qlik-default` which will be the prefix for all kubernetes resources created by the cli under this context latter on. New context and configuration can be created by the cli. + +```console +$ qliksense config -h +do operations on/around CR + +Usage: + qliksense config [command] + +Available Commands: + apply generate the patchs and apply manifests to k8s + list-contexts retrieves the contexts and lists them + set configure a key value pair into the current context + set-configs set configurations into the qliksense context as key-value pairs + set-context Sets the context in which the Kubernetes cluster and resources live in + set-secrets set secrets configurations into the qliksense context as key-value pairs + view view the qliksense operator CR + +Flags: + -h, --help help for config + +Use "qliksense config [command] --help" for more information about a command. +``` + +`qliksense` cli works in two modes + +- with a git repo fork/clone of [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) +- without git repo + +## Without git repo + +In this mode `qliksense` CLI download the specified version from [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) and put it into folder `~/.qliksense/contexts//qlik-k8s`. + +The qliksense cli create a CR for the qliksense operator and all the config operations are peformed to edit the CR. So when `qliksense install` or `qliksense config apply` both generate patches in local file system (i.e `~/.qliksense/contexts//qlik-k8s`) and install those manifests into the cluster and create a custom resoruce (CR) for the `qliksene operator` then the operator make association to the isntalled resoruces so that when `qliksenes uninstall` is performed the operator can delete all those kubernetes resources related to QSEoK for the current context. + +## With a git repo + +User has to create fork or clone of [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) and push it to their own git server. When user perform `qliksense install` or `qliksene config apply` the qliksense operator do these tasks + +- downloads the corresponding version of manifests from the user's git repo. +- generate kustomize patches +- install kubernetes resoruces +- push those generated patches into a new branch in the provided git repo. so that user user can merge those patches into their master branch. +- spinup a cornjob to monitor master branch. If user modifies anything in the master branch those changes will be applied into the cluster. This is a light weight `git-ops` model + +This is how repo info is provided into the CR + +```console +qliksense config set git.repository="https://github.com/my-org/qliksense-k8s" + +qliksense config set git.accessToken=blablalaala +``` diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..e688493 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,30 @@ +# Getting started + +## Requirements + +- `kubectl` need to be installed and configured properly so that `kubectl` can connect to the kubernetes cluser. The `qliksense` CLI uses `kubectl` under the hood to perform operations on cluster + - (Docker Desktop setup tested for these instructions) + +## Download + +- Download the appropriate executable for your platform from the [releases page](https://github.com/qlik-oss/sense-installer/releases) and rename it to `qliksense`. All the examplease down below uses `qliksense`. + +## Quick start + +- To download the version `v0.0.2` from qliksense-k8s [releases](https://github.com/qlik-oss/qliksense-k8s/releases). + +```shell +$qliksense fetch v0.0.2 +``` + +- To install CRDs for QSEoK and qliksense operator into the kubernetes cluster. + +```shell +$qliksense crds install --all +``` + +- To install QSEoK into a namespace in the kubernetes cluster where `kubectl` is pointing to. + +```shell +$qliksense install --acceptEULA="yes" +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..64645a7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,19 @@ +# Overview + +The Qlik Sense installer CLI (qliksense) provides an imperative interface to many of the configurations that need to be applied against the declarative structure described in [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s). This cli facilitates: + +- installation of QSEoK +- installation of qliksense operator to manage QSEoK +- air gapped installation of QSEoK + +This is a technology preview that uses Qlik modified [kustomize](https://github.com/qlik-oss/kustomize) to kubernetes manifests of the versions of the [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) repository. + +For each version of a qliksense edge build there should be a corresponding release in [qliksense-k8s] repository under [releases](https://github.com/qlik-oss/qliksense-k8s/releases) + +## Future Direction + +- More operations: + - Expand preflight checks + - backup/restore operations + - fully support airgap installation of QSEoK + - restore unwanted deletion of kubernetes resources diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f938680 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,18 @@ +site_name: Qlik Sense installer +repo_url: 'https://github.com/qlik-oss/sense-installer' +strict: true +theme: + name: "material" + palette: + primary: 'green' + accent: 'indigo' +markdown_extensions: + - toc: + permalink: true + - admonition +nav: + - Overview: index.md + - getting_started.md + - concepts.md + - air_gap.md + - Releases ⧉: https://github.com/qlik-oss/sense-installer/releases