diff --git a/README.md b/README.md index b515e4d..3ccfecc 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,12 @@ -# (WIP) Qlik Sense installation and operations CLI +# (WIP) Qlik Sense on Kubernetes installation and operations CLI ## Documentation -To learn more about Qlik Sense installer go to https://qlik-oss.github.io/sense-installer/ +To learn more about Qlik Sense on Kubernetes CLI go to https://qlik-oss.github.io/sense-installer/ ## About -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 +The QSEoK 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 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. diff --git a/docs/command_reference.md b/docs/command_reference.md index b684aea..86ed568 100644 --- a/docs/command_reference.md +++ b/docs/command_reference.md @@ -1,13 +1,13 @@ -# qliksense command reference +# CLI reference -## qliksense apply +### qliksense apply -`qliksense apply` command takes input a cr file or input from pipe +`qliksense apply` command takes input from a file or from pipe - `qliksense apply -f cr-file.yaml` - `cat cr-file.yaml | qliksense apply -f -` -the content of `cr-file.yaml` should be something similar +The content of `cr-file.yaml` should be something like the following: ```yaml apiVersion: qlik.com/v1 @@ -27,33 +27,34 @@ spec: value: mongodb://qlik-test-mongodb:27017/qliksense?ssl=false profile: docker-desktop rotateKeys: "yes" - ``` +``` -This will do everything `qliksense load` does and install the qliksense into the cluster. +`qliksense apply` does everything `qliksense load` does but will install Qlik Sense into the cluster as well -## qliksense load +### qliksense load -`qliksense load` command takes input a cr file or input from pipe. +`qliksense load` command takes input from a file or from pipe - `qliksense load -f cr-file.yaml` - `cat cr-file.yaml | qliksense load -f -` -This will load the CR into `${QLIKSENSE_HOME}` folder, create context structure and set the current context to that CR. +This will load the Custom Resource (CR) into `${QLIKSENSE_HOME}` folder, create context structure and set the current context to that CR. + This will also encrypt the secrets from CR while writing the CR into the disk. -## qliksense about +### qliksense about -About action will display inside information regarding [qliksense-k8](https://github.com/qlik-oss/qliksense-k8s) release. +`qliksense about` command will display information about [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) release. -it will support following flags +It supports the following flags: - `qliksense about 1.0.0` display default profile for tag `1.0.0`. - `qliksense about 1.0.0 --profile=docker-desktop` -- `qliksense about` - - assuming current directory has `manifests/docker-desktop` - - or get version information from pull of `qliksense-k8s` `master` +- If `qliksense about` is ran without flags, then it displays + - Information of the release defined in `manifests/docker-desktop` (if it exist), otherwise + - Get version information from `master` branch in `qliksense-k8s` repository -using other supported commands user might have built the CR into the location `~/.qliksense/myqliksense.yaml` +Using other supported commands user might have built the CR into the location `~/.qliksense/myqliksense.yaml` ```yaml apiVersion: qlik.com/v1 @@ -62,7 +63,7 @@ metadata: name: myqliksense spec: profile: docker-desktop - manifestsRoot: /Usr/ddd/my-k8-repo/manifests + manifestsRoot: /Usr/xyz/my-k8-repo/manifests namespace: myqliksense storageClassName: efs configs: @@ -77,31 +78,30 @@ spec: valueFromKey: messagingPassword ``` -In that case the command would be +In this case, the result of `qliksense about` command would display information from: -- `qliksense about` - - display from `/Usr/ddd/my-k8-repo/manifests/docker-desktop` location - - pull from `master` if directory invalid/empty +- `/Usr/xyz/my-k8-repo/manifests/docker-desktop` location, or +- Pull and show information from `master` branch if the directory is invalid or empty -## qliksense config +### qliksense config -Config action will perform operations on configurations and contexts regarding the [qliksense-k8](https://github.com/qlik-oss/qliksense-k8s) release. +`qliksense config` will perform operations on configurations and contexts regarding the [qliksense-k8](https://github.com/qlik-oss/qliksense-k8s) release. -it will support following commands: +It supports the following flags: -- `qliksense config apply` - generate the patchs and apply manifests to k8s -- `qliksense config list-contexts` - retrieves the contexts and lists them -- `qliksense config set` - configure a key value pair into the current context -- `qliksense config set-configs` - set configurations into the qliksense context as key-value pairs -- `qliksense config set-context` - sets the context in which the Kubernetes cluster and resources live in -- `qliksense config set-secrets .="" --secret=false` - set secrets configurations into the qliksense context as key-value pairs and show encrypted value as part of CR -- `qliksense config set-secrets .="" --secret=true` - set secrets configurations into the qliksense context as key-value pairs and show a key reference to the created Kubernetes secret resource as part of the CR +- `qliksense config apply` - generate the patches and apply manifests to K8s +- `qliksense config list-contexts` - get and list contexts +- `qliksense config set` - configure a key-value pair into the current context +- `qliksense config set-configs` - set configurations into qliksense context as key-value pairs +- `qliksense config set-context` - sets the Kubernetes context where resources are located +- `qliksense config set-secrets .="" --secret=false` - set secrets configurations into qliksense context as key-value pairs and show encrypted value as part of CR +- `qliksense config set-secrets .="" --secret=true` - set secrets configurations into qliksense context as key-value pairs and show a key reference to the created Kubernetes secret resource as part of the CR - `qliksense config view` - view the qliksense operator CR -- `qliksense config delete-context` - deletes a specific context locally (not in-cluster). Deletes context in spec of `config.yaml` and locally deletes entire folder of specified context (does not delete in-cluster secrets) +- `qliksense config delete-context` - deletes a specific context locally (not in-cluster). Deletes context in spec of `config.yaml` and locally deletes entire folder of specified context (does not delete secrets from cluster) -the global file that abstracts all the contexts is `config.yaml`, located at: `~/.qliksense/config.yaml`: +The global file which abstracts all contexts is `~/.qliksense/config.yaml` ```yaml apiVersion: config.qlik.com/v1 kind: QliksenseConfig @@ -110,10 +110,10 @@ metadata: spec: contexts: - name: qlik-default - crFile: /Users/fff/.qliksense/contexts/qlik-default/qlik-default.yaml + crFile: /Users/xyz/.qliksense/contexts/qlik-default/qlik-default.yaml - name: myqliksense - crFile: /Users/fff/.qliksense/contexts/myqliksense/myqliksense.yaml + crFile: /Users/xyz/.qliksense/contexts/myqliksense/myqliksense.yaml - name: hello - crFile: /Users/fff/.qliksense/contexts/hello/hello.yaml + crFile: /Users/xyz/.qliksense/contexts/hello/hello.yaml currentContext: hello -``` \ No newline at end of file +``` diff --git a/docs/concepts.md b/docs/concepts.md index 56b7cf3..df61665 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,4 +1,4 @@ -# How qliksense cli works +# How CLI works At the initialization, `qliksense` cli creates few files in the director `~/.qliksene` and it contains following files: @@ -48,14 +48,14 @@ qliksense config -h In this mode `qliksense` CLI downloads the specified version from [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) and places it in `~/.qliksense/contexts//qlik-k8s` folder. -The qliksense cli creates a CR for the QlikSense operator and all config operations are peformed to edit the CR. +The qliksense cli creates a CR for the QlikSense operator and all config operations are performed to edit the CR. `qliksense install` or `qliksense config apply` will generate patches in local file system (i.e `~/.qliksense/contexts//qlik-k8s`) and - Install those manifests into the cluster -- Create a custom resoruce (CR) for the `qliksene operator`. +- Create a custom resource (CR) for the `qliksene operator`. -The operator makes the association to the installed resoruces so that when `qliksense uninstall` is performed the operator can delete all kubernetes resources related to QSEoK for the current context. +The operator makes the association to the installed resources so that when `qliksense uninstall` is performed the operator can delete all kubernetes resources related to QSEoK for the current context. ## With a git repo @@ -94,4 +94,3 @@ spec: image: qlik-docker-oss.bintray.io/qliksense-repo-watcher .... ``` - diff --git a/docs/getting_started.md b/docs/getting_started.md index d4c94da..5614b30 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -5,7 +5,7 @@ - Kubernetes cluster (Docker Desktop with enabled Kubernetes) - `kubectl` installed, configured and able to communicate with kubernetes cluster. _`qliksense` CLI uses `kubectl` under the hood to perform operations on cluster_ -## Installing Sense installer +## Installing `qliksense` CLI Download the executable for your platform from [releases page](https://github.com/qlik-oss/sense-installer/releases) and rename it to `qliksense` diff --git a/docs/index.md b/docs/index.md index 9ab0157..63cc37e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,15 @@ # 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: +The Qlik Sense on Kubernetes 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). + +The CLI facilitates: - Installation of QSEoK - Installation of qliksense operator to manage QSEoK - Air gapped installation of QSEoK !!! info "" - This is a technology preview that uses Qlik modified [kustomize](https://github.com/qlik-oss/kustomize) for kubernetes manifests on [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) repository + This is a technology preview that uses Qlik modified [kustomize](https://github.com/qlik-oss/kustomize) for Kubernetes manifests on [qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s) repository !!! info "" See QlikSense [edge releases on qliksense-k8s](https://github.com/qlik-oss/qliksense-k8s/releases) repository - -## Future Direction - -Operations: - -- Expand preflight checks -- Backup/restore operations -- Fully support airgap installation of QSEoK -- Restore unwanted deletion of kubernetes resources diff --git a/docs/preflight_checks.md b/docs/preflight_checks.md index 760260d..796dbc2 100644 --- a/docs/preflight_checks.md +++ b/docs/preflight_checks.md @@ -1,10 +1,12 @@ -##Preflight checks +# Preflight checks + Preflight checks provide pre-installation cluster conformance testing and validation before we install qliksense on the cluster. We gather a suite of conformance tests that can be easily written and run on the target cluster to verify that cluster-specific requirements are met. + The suite consists of a set of `collectors` which run the specifications of every test and `analyzers` which analyze the results of every test run by the collector. We support the following tests at the moment as part of preflight checks, and the range of the suite will be expanded in future. Run the following command to view help about the commands supported by preflight at any moment: -```console +```shell $ qliksense preflight perform preflight checks on the cluster @@ -26,7 +28,7 @@ Flags: ### DNS check Run the following command to perform preflight DNS check. We setup a kubernetes deployment and try to reach it as part of establishing DNS connectivity in this check. The expected output should be similar to the one shown below. -```console +```shell $ qliksense preflight dns Preflight DNS check @@ -49,7 +51,7 @@ Deleted deployment: dep-dns-preflight-check ### Kubernetes version check We check the version of the target kubernetes cluster and ensure that it falls in the valid range of kubernetes versions that are supported by qliksense. The command to run this check and the expected similar output are as shown below: -```console +```shell $ qliksense preflight k8s-version Preflight kubernetes minimum version check @@ -64,7 +66,7 @@ Completed Preflight kubernetes minimum version check ### Service check We use the commmand below to test if we are able to create a service in the cluster. -```console +```shell $ qliksense preflight service Preflight service check @@ -80,7 +82,7 @@ Completed preflight service check ### Deployment check We use the commmand below to test if we are able to create a deployment in the cluster. After the test exexutes, we wait until the created deployment terminates before we exit the command. -```console +```shell $ qliksense preflight deployment Preflight deployment check @@ -95,7 +97,7 @@ Completed preflight deployment check ### Pod check We use the commmand below to test if we are able to create a pod in the cluster. -```console +```shell $ qliksense preflight pod Preflight pod check @@ -217,7 +219,7 @@ Completed preflight mongodb check ### Running all checks Run the command shown below to execute all preflight checks. -```console +```shell $ qliksense preflight all --mongodb-url= OR $ qliksense preflight all diff --git a/mkdocs.yml b/mkdocs.yml index 784d13f..4f05872 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Qlik Sense installer +site_name: Qlik Sense on Kubernetes CLI repo_url: 'https://github.com/qlik-oss/sense-installer' strict: true theme: