Add mkdocs

Signed-off-by: Raul Sevilla <[email protected]>
rsevilla87 · Dec 6, 2020 · 71cbd47 · 71cbd47
1 parent 55d67df
commit 71cbd47
Show file tree

Hide file tree

Showing 12 changed files with 514 additions and 483 deletions.
diff --git a/AUTHORS.md b/AUTHORS.md
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -0,0 +1 @@
+docs/AUTHORS.md
diff --git a/README.md b/README.md
diff --git a/docs/AUTHORS.md b/docs/AUTHORS.md
@@ -0,0 +1,7 @@
+# Development Lead
+
+- Raúl Sevilla Cañavate [rsevilla87](https://github.com/rsevilla87)
+
+# Contributors
+
+None yet. Why not be the first?
diff --git a/docs/CLI.md b/docs/CLI.md
@@ -0,0 +1,77 @@
+kube-burner is basically a binary client with currently the following options:
+
+```console
+$ kube-burner help
+Kube-burner 🔥
+
+Tool aimed at stressing a kubernetes cluster by creating or deleting lot of objects.
+
+Usage:
+  kube-burner [command]
+
+Available Commands:
+  completion  Generates completion scripts for bash shell
+  destroy     Destroy old namespaces labeled with the given UUID.
+  help        Help about any command
+  index       Index metrics from the given time range
+  init        Launch benchmark
+  version     Print the version number of kube-burner
+
+Flags:
+  -h, --help   help for kube-burner
+
+Use "kube-burner [command] --help" for more information about a command.
+```
+
+# Init
+
+This option is meant to run Kube-burner benchmark, and it supports the these flags:
+
+  - config: Path or URL to a valid configuration file.
+  - log-level: Logging level. Default `info`
+  - prometheus-url: Prometheus full URL. i.e. `https://prometheus-k8s-openshift-monitoring.apps.rsevilla.stress.mycluster.example.com`
+  - metrics-profile: Path to a valid metrics profile file. Default `metrics.yaml`
+  - token: Prometheus Bearer token.
+  - username: Prometheus username for basic authentication.
+  - password: Prometheus password for basic authentication.
+  - skip-tls-verify: Skip TLS verification for prometheus. Default `true`
+  - step: Prometheus step size. Default `30s`
+  - UUID: Benchmark UUID.
+
+**Note**: Both basic authentication and Bearer authentication need credentials able to query the given Prometheus API.
+
+With the above, triggering kube-burner would be as simple as:
+
+```console
+$ kube-burner init -c cfg.yml -u https://prometheus-k8s-openshift-monitoring.apps.rsevilla.stress.mycluster.example.com -t ${token} --uuid 67f9ec6d-6a9e-46b6-a3bb-065cde988790`
+```
+
+Kube-burner also supports remote configuration files served by a web server, to use it, rather than a path pass a URL like below:
+
+```console
+$ kube-burner init -c http://web.domain.com:8080/cfg.yml -t ${token} --uuid 67f9ec6d-6a9e-46b6-a3bb-065cde988790`
+```
+
+If you have no interest in collecting prometheus metrics, kube-burner can also be launched w/o any prometheus endpoint, this will disable metrics collection.
+
+```console
+$ kube-burner init -c cfg.yml --uuid 67f9ec6d-6a9e-46b6-a3bb-065cde988790`
+```
+
+# Index
+
+This option can be used to collect and index the metrics from a given time range. The time range is given by:
+
+  - start: Epoch start time. Defaults to one hour before the current time.
+  - End: Epoch end time. Defaults to the current time.
+
+# Destroy
+
+This option requires the above `config` and `UUID` flags to destroy all namespaces labeled with `kube-burner-uuid=<UUID>`.
+
+# Completion
+Generates bash a completion script that can be imported with:
+`. <(kube-burner completion)`
+
+Or permanently imported with:
+`kube-burner completion > /etc/bash_completion.d/kube-burner`
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -0,0 +1,160 @@
+
+All the magic `kube-burner` does is described in the configuration file. As previoysly mentioned the location of this configuration file is provided by the flag `-c`. This file is written in YAML format and has several sections.
+
+# Global 
+
+In this section is described global job configuration, it holds the following parameters:
+
+| Option           | Description                                                                                              | Type           | Example        | Default     |
+|------------------|----------------------------------------------------------------------------------------------------------|----------------|----------------|-------------|
+| kubeconfig       | Points to a valid kubeconfig file. Can be omitted if using the KUBECONFIG environment variable, or running from a pod | String  | ~/mykubeconfig | in-cluster |             |
+| writeToFile      | Whether to dump collected metrics to files                                                               | Boolean        | true           | true        |
+| metricsDirectory | Directory where collected metrics will be dumped into. It will be created if it doesn't exist previously | String         | ./metrics      | ./collected-metrics | 
+| measurements     | List of measurements. Detailed in the [measurements section](#Measurements)                              | List           | -              | []          |
+| indexerConfig    | Holds the indexer configuration. Detailed in the [indexers section](#Indexers)                           | Object         | -              | -           |
+
+# Jobs
+
+This section contains the list of jobs `kube-burner` will execute. Each job can hold the following parameters.
+
+| Option               | Description                                                                      | Type    | Example  | Default |
+|----------------------|----------------------------------------------------------------------------------|---------|----------|---------|
+| name                 | Job name                                                                         | String  | myjob    | ""      |
+| jobType              | Type of job to execute. More details at [job types](#job-types)                  | string  | create   | create  |
+| jobIterations        | How many times to execute the job                                                | Integer | 10       | 0       |
+| namespace            | Namespace base name to use                                                       | String  | firstjob | ""      |
+| namespacedIterations | Whether to create a namespace per job iteration                                  | Boolean | true     | true    |
+| cleanup              | Cleanup clean up old namespaces                                                  | Boolean | true     | true    |
+| podWait              | Wait for all pods to be running before moving forward to the next job iteration  | Boolean | true     | true    |
+| waitWhenFinished     | Wait for all pods to be running when all iterations are completed                | Boolean | true     | false   |
+| maxWaitTimeout       | Maximum wait timeout in seconds. (If podWait is enabled this timeout will be reseted with each iteration) | Integer | 1h     | 12h |
+| waitFor              | List containing the objects Kind wait for. Wait for all if empty                 | List    | ["Deployment", "Build", "DaemonSet"]| []      |
+| jobIterationDelay    | How long to wait between each job iteration                                      | Duration| 2s       | 0s      |
+| jobPause             | How long to pause after finishing the job                                        | Duration| 10s      | 0s      |
+| qps                  | Limit object creation queries per second                                         | Integer | 25       | 0       |
+| burst                | Maximum burst for throttle                                                       | Integer | 50       | 0       |
+| objects              | List of objects the job will create. Detailed on the [objects section](#objects) | List    | -        | []      |
+| verifyObjects        | Verify object count after running each job. Return code will be 1 if failed      | Boolean | true     | true    |
+| errorOnVerify        | Exit with rc 1 before indexing when objects verification fails                   | Boolean | true     | false   |
+
+
+A valid example of a configuration file can be found at [./examples/cfg.yml](https://github.com/cloud-bulldozer/kube-burner/blob/master/examples/cfg.yml)
+
+# Objects
+
+The objects created by `kube-burner` are rendered using the default golang's [template library](https://golang.org/pkg/text/template/).
+Each object element supports the following parameters:
+
+| Option               | Description                                                       | Type    | Example                                             | Default |
+|----------------------|-------------------------------------------------------------------|---------|-----------------------------------------------------|---------|
+| objectTemplate       | Object template file or URL                                       | String  | deployment.yml or https://domain.com/deployment.yml | ""      |
+| replicas             | How replicas of this object to create per job iteration           | Integer | 10                                                  | -       |
+| inputVars            | Map of arbitrary input variables to inject to the object template | Object  | -                                                   | -       |
+
+It's important to note that all objects created by kube-burner are labeled with. `kube-burner-uuid=<UUID>,kube-burner-job=<jobName>,kube-burner-index=<objectIndex>`
+
+
+# Job types
+
+kube-burner support two types of jobs with different parameters each. The default job type is __create__. Which basically creates objects as described in the section [objects](#objects).
+
+The other type is __delete__, this type of job deletes objects described in the objects list. Using delete as job type the objects list would have the following structure.
+
+```yaml
+objects:
+- kind: Deployment
+  labelSelector: {kube-burner-job: cluster-density}
+  apiVersion: apps/v1
+
+- kind: Secret
+  labelSelector: {kube-burner-job: cluster-density}
+```
+Where:
+- kind: Object kind of the k8s object to delete.
+- labelSelector: Map with the labelSelector.
+- apiVersion: API version from the k8s object.
+
+As mentioned previously, all objects created by kube-burner are labeled with `kube-burner-uuid=<UUID>,kube-burner-job=<jobName>,kube-burner-index=<objectIndex>`. Thanks to this we could design a workload with one job to create objects and another one able to remove the objects created by the previous
+
+```yaml
+jobs:
+- name: create-objects
+  namespace: job-namespace
+  jobIterations: 100
+  objects:
+  - objectTemplate: deployment.yml
+    replicas: 10
+
+  - objectTemplate: service.yml
+    replicas: 10
+
+- name: remove-objects
+  jobType: delete
+  objects:
+  - kind: Deployment
+    labelSelector: {kube-burner-job: create-objects}
+    apiVersion: apps/v1
+
+  - kind: Secret
+    labelSelector: {kube-burner-job: create-objects}
+```
+
+This job type supports the some of the same parameters as the create job type:
+- **waitForDeletion**: Wait for objects to be deleted before finishing the job. Defaults to true
+- name
+- qps
+- burst
+- jobPause
+
+# Injected variables
+
+All object templates are injected a series of variables by default:
+
+- Iteration: Job iteration number.
+- Replica: Object replica number. Keep in mind that this number is reset to 1 with each job iteration.
+- JobName: Job name.
+- UUID: Benchmark UUID.
+
+In addition, you can also inject arbitrary variables with the option **inputVars** from the objectTemplate object:
+
+```yaml
+    - objectTemplate: service.yml
+      replicas: 2
+      inputVars:
+        port: 80
+        targetPort: 8080
+```
+
+The following code snippet shows an example of a k8s service using these variables:
+
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: sleep-app-{{ .Iteration }}-{{ .Replica }}
+  labels:
+    name: my-app-{{ .Iteration }}-{{ .Replica }}
+spec:
+  selector:
+    app: sleep-app-{{ .Iteration }}-{{ .Replica }}
+  ports:
+  - name: serviceport
+    protocol: TCP
+    port: "{{ .port }}"
+    targetPort: "{{ .targetPort }}"
+  type: ClusterIP
+```
+
+It's worth to say that you can also use [golang template semantics](https://golang.org/pkg/text/template/) in your *objectTemplate* files.
+
+```yaml
+kind: ImageStream
+apiVersion: image.openshift.io/v1
+metadata:
+  name: {{.prefix}}-{{.Replica}}
+spec:
+{{ if .image }}
+  dockerImageRepository: {{.image}}
+{{ end }}
+```
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,19 @@
+If you want to contribute to kube-burner, submit a Pull Request or Issue.
+Kube-burner uses `golangci-lint` to run linters. Prior to send a PR, ensure to execute linters with `make lint`.
+
+# Requirements
+
+- `golang >= 1.13`
+- `golang-ci-lint`
+- `make`
+
+# Building
+
+To build kube-burner just execute `make build`, once finished `kube-burner`'s binary should be available at `./bin/kube-burner`
+
+```console
+$ make build
+building kube-burner 0.1.0
+GOPATH=/home/rsevilla/go
+CGO_ENABLED=0 go build -v -mod vendor -ldflags "-X github.com/cloud-bulldozer/kube-burner/version.GitCommit=d91c8cc35cb458a4b80a5050704a51c7c6e35076 -X github.com/cloud-bulldozer/kube-burner/version.BuildDate=2020-08-19-19:10:09 -X github.com/cloud-bulldozer/kube-burner/version.GitBranch=master" -o bin/kube-burner
+```
diff --git a/docs/INDEXERS.md b/docs/INDEXERS.md
@@ -0,0 +1,31 @@
+# Configuration 
+
+`kube-burner` is able to **index the collected prometheus metrics** into a given Indexer. 
+The indexer configuration is described in the `indexerConfig` section and can be configured with the following parameters:
+
+
+| Option               | Description           | Type     | Example    | Default |
+|----------------------|-----------------------|----------|------------|---------|
+| enabled              | Enable indexing       | Boolean  | true       | false   |
+| type                 | Type of indexer       | String   | elastic    | ""      | 
+
+
+# Elastic
+
+Index documents in Elasticsearch 7 instances.
+
+In addition, each indexer has its own configuration parameters.
+
+----
+
+The `elastic` indexer is configured by the parameters below:
+
+| Option               | Description                                       | Type        | Example                                  | Default |
+|----------------------|---------------------------------------------------|-------------|------------------------------------------|---------|
+| esServers            | List of ES instances                              | List        | [https://elastic.apps.rsevilla.org:9200] | ""      |
+| defaultIndex         | Default index to send the prometheus metrics into | String      | kube-burner                              | ""      | 
+| insecureSkipVerify   | TLS certificate verification                      | Boolean     | true                                     | false   |
+
+**Note**: It's possible to index documents in an authenticated ES instance using the notation `http(s)://[username]:[password]@[address]:[port]` in the *esServers* parameter.
+
+