Using Cluster Loader

Cluster Loader is a tool that deploys large numbers of various objects to a cluster, which creates user-defined cluster objects. Build, configure, and run Cluster Loader to measure performance metrics of your OKD deployment at various cluster states.

Installing Cluster Loader

Procedure

  1. To pull the container image, run:

    1. $ podman pull quay.io/openshift/origin-tests:4.6

Running Cluster Loader

Prerequisites

  • The repository will prompt you to authenticate. The registry credentials allow you to access the image, which is not publicly available. Use your existing authentication credentials from installation.

Procedure

  1. Execute Cluster Loader using the built-in test configuration, which deploys five template builds and waits for them to complete:

    1. $ podman run -v ${LOCAL_KUBECONFIG}:/root/.kube/config:z -i \
    2. quay.io/openshift/origin-tests:4.6 /bin/bash -c 'export KUBECONFIG=/root/.kube/config && \
    3. openshift-tests run-test "[sig-scalability][Feature:Performance] Load cluster \
    4. should populate the cluster [Slow][Serial] [Suite:openshift]"'

    Alternatively, execute Cluster Loader with a user-defined configuration by setting the environment variable for VIPERCONFIG:

    1. $ podman run -v ${LOCAL_KUBECONFIG}:/root/.kube/config:z \
    2. -v ${LOCAL_CONFIG_FILE_PATH}:/root/configs/:z \
    3. -i quay.io/openshift/origin-tests:4.6 \
    4. /bin/bash -c 'KUBECONFIG=/root/.kube/config VIPERCONFIG=/root/configs/test.yaml \
    5. openshift-tests run-test "[sig-scalability][Feature:Performance] Load cluster \
    6. should populate the cluster [Slow][Serial] [Suite:openshift]"'

    In this example, ${LOCAL_KUBECONFIG} refers to the path to the kubeconfig on your local file system. Also, there is a directory called ${LOCAL_CONFIG_FILE_PATH}, which is mounted into the container that contains a configuration file called test.yaml. Additionally, if the test.yaml references any external template files or podspec files, they should also be mounted into the container.

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:

  1. provider: local (1)
  2. ClusterLoader:
  3. cleanup: true
  4. projects:
  5. - num: 1
  6. basename: clusterloader-cakephp-mysql
  7. tuning: default
  8. ifexists: reuse
  9. templates:
  10. - num: 1
  11. file: cakephp-mysql.json
  12. - num: 1
  13. basename: clusterloader-dancer-mysql
  14. tuning: default
  15. ifexists: reuse
  16. templates:
  17. - num: 1
  18. file: dancer-mysql.json
  19. - num: 1
  20. basename: clusterloader-django-postgresql
  21. tuning: default
  22. ifexists: reuse
  23. templates:
  24. - num: 1
  25. file: django-postgresql.json
  26. - num: 1
  27. basename: clusterloader-nodejs-mongodb
  28. tuning: default
  29. ifexists: reuse
  30. templates:
  31. - num: 1
  32. file: quickstarts/nodejs-mongodb.json
  33. - num: 1
  34. basename: clusterloader-rails-postgresql
  35. tuning: default
  36. templates:
  37. - num: 1
  38. file: rails-postgresql.json
  39. tuningsets: (2)
  40. - name: default
  41. pods:
  42. stepping: (3)
  43. stepsize: 5
  44. pause: 0 s
  45. rate_limit: (4)
  46. delay: 0 ms
1Optional setting for end-to-end tests. Set to local to avoid extra log messages.
2The 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.
3Stepping will pause for M seconds after each N objects are created.
4Rate limiting will wait M milliseconds between the creation of objects.

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

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

Table 1. Top-level Cluster Loader Fields
FieldDescription

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.

Table 2. Fields under projects
FieldDescription

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 config map name and the value is a path to a file from which you create the config map.

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.

Table 3. Fields under pods and templates
FieldDescription

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 pod spec 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.

Table 4. Fields under tuningsets
FieldDescription

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.

Table 5. Fields under tuningsets pods or tuningsets templates
FieldDescription

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.

Table 6. Fields under tuningsets pods or tuningsets templates, stepping
FieldDescription

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.

Table 7. Fields under sync
FieldDescription

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].

Known issues

  • Cluster Loader fails when called without configuration. (BZ#1761925)

  • If the IDENTIFIER parameter is not defined in user templates, template creation fails with error: unknown parameter name "IDENTIFIER". If you deploy templates, add this parameter to your template to avoid this error:

    1. {
    2. "name": "IDENTIFIER",
    3. "description": "Number to append to the name of resources",
    4. "value": "1"
    5. }

    If you deploy pods, adding the parameter is unnecessary.