openshift-docs/modules/configuring-cluster-loader.adoc

// Module included in the following assemblies:
//
// scalability_and_performance/using-cluster-loader.adoc

[id="configuring_cluster_loader_{context}"]
= Configuring Cluster Loader

The tool creates multiple namespaces (projects), which contain multiple
templates or Pods.

== Example Cluster Loader configuration file

Cluster Loader’s configuration file is a basic YAML file:

[source,yaml]
----
provider: local <1>
ClusterLoader:
  cleanup: true
  projects:
    - num: 1
      basename: clusterloader-cakephp-mysql
      tuning: default
      ifexists: reuse
      templates:
        - num: 1
          file: cakephp-mysql.json

    - num: 1
      basename: clusterloader-dancer-mysql
      tuning: default
      ifexists: reuse
      templates:
        - num: 1
          file: dancer-mysql.json

    - num: 1
      basename: clusterloader-django-postgresql
      tuning: default
      ifexists: reuse
      templates:
        - num: 1
          file: django-postgresql.json

    - num: 1
      basename: clusterloader-nodejs-mongodb
      tuning: default
      ifexists: reuse
      templates:
        - num: 1
          file: quickstarts/nodejs-mongodb.json

    - num: 1
      basename: clusterloader-rails-postgresql
      tuning: default
      templates:
        - num: 1
          file: rails-postgresql.json

  tuningsets: <2>
    - name: default
      pods:
        stepping: <3>
          stepsize: 5
          pause: 0 s
        rate_limit: <4>
          delay: 0 ms
----
<1> Optional setting for end-to-end tests. Set to `local` to avoid extra log messages.
<2> The tuning sets allow rate limiting and stepping, the ability to create several
batches of Pods while pausing in between sets. Cluster Loader monitors
completion of the previous step before continuing.
<3> Stepping will pause for `M` seconds after each `N` objects are created.
<4> Rate limiting will wait `M` milliseconds between the creation of objects.

This example assumes that references to any external template files or podspec
files are also mounted into the container.

[IMPORTANT]
====
If you are running Cluster Loader on Microsoft Azure, then you must set the
`AZURE_AUTH_LOCATION` variable to a file that contains the output of
`terraform.azure.auto.tfvars.json`, which is present in the installer directory.
====

== Configuration fields

.Top-level Cluster Loader Fields
|===
|Field |Description

|`cleanup`
|Set to `true` or `false`. One definition per configuration. If set to `true`,
`cleanup` deletes all namespaces (projects) created by Cluster Loader at the
end of the test.

|`projects`
|A sub-object with one or many definition(s). Under `projects`, each
namespace to create is defined and `projects` has several mandatory subheadings.

|`tuningsets`
|A sub-object with one definition per configuration. `tuningsets` allows the user
to define a tuning set to add configurable timing to project or object creation
(Pods, templates, and so on).

|`sync`
|An optional sub-object with one definition per configuration. Adds synchronization
possibilities during object creation.
|===

.Fields under `projects`
|===
|Field |Description

|`num`
|An integer. One definition of the count of how many projects to create.

|`basename`
|A string. One definition of the base name for the project. The count of
identical namespaces will be appended to `Basename` to prevent collisions.

|`tuning`
|A string. One definition of what tuning set you want to apply to the objects,
which you deploy inside this namespace.

|`ifexists`
|A string containing either `reuse` or `delete`. Defines what the tool does if
it finds a project or namespace that has the same name of the project or
namespace it creates during execution.

|`configmaps`
|A list of key-value pairs. The key is the ConfigMap name and the value is a
path to a file from which you create the ConfigMap.

|`secrets`
|A list of key-value pairs. The key is the secret name and the value is a path to
a file from which you create the secret.

|`pods`
|A sub-object with one or many definition(s) of Pods to deploy.

|`templates`
|A sub-object with one or many definition(s) of templates to deploy.
|===

.Fields under `pods` and `templates`
|===
|Field |Description

|`num`
|An integer. The number of Pods or templates to deploy.

|`image`
|A string. The docker image URL to a repository where it can be pulled.

|`basename`
| A string. One definition of the base name for the template (or pod) that you want to create.

|`file`
|A string. The path to a local file, which is either a PodSpec or template to be created.

|`parameters`
|Key-value pairs. Under `parameters`, you can specify a list of values to
override in the pod or template.
|===

.Fields under `tuningsets`
|===
|Field |Description

|`name`
|A string. The name of the tuning set which will match the name specified when
defining a tuning in a project.

|`pods`
|A sub-object identifying the `tuningsets` that will apply to Pods.

|`templates`
|A sub-object identifying the `tuningsets` that will apply to templates.
|===

.Fields under `tuningsets` `pods` or `tuningsets` `templates`
|===
|Field |Description

|`stepping`
|A sub-object. A stepping configuration used if you want to create an object in a
step creation pattern.

|`rate_limit`
|A sub-object. A rate-limiting tuning set configuration to limit the object
creation rate.
|===

.Fields under `tuningsets` `pods` or `tuningsets` `templates`, `stepping`
|===
|Field |Description

|`stepsize`
|An integer. How many objects to create before pausing object creation.

|`pause`
|An integer. How many seconds to pause after creating the number of objects
defined in `stepsize`.

|`timeout`
|An integer. How many seconds to wait before failure if the object creation is
not successful.

|`delay`
|An integer. How many milliseconds (ms) to wait between creation requests.
|===

.Fields under `sync`
|===
|Field |Description

|`server`
|A sub-object with `enabled` and `port` fields. The boolean `enabled` defines
whether to start an HTTP server for pod synchronization. The integer `port`
defines the HTTP server port to listen on (`9090` by default).

|`running`
|A boolean. Wait for Pods with labels matching `selectors` to go into `Running`
state.

|`succeeded`
|A boolean. Wait for Pods with labels matching `selectors` to go into `Completed`
state.

|`selectors`
|A list of selectors to match Pods in `Running` or `Completed` states.

|`timeout`
|A string. The synchronization timeout period to wait for Pods in `Running` or
`Completed` states. For values that are not `0`, use units:
[ns\|us\|ms\|s\|m\|h].
|===