diff --git a/src/data/nav.yaml b/src/data/nav.yaml index ffacaed5..43028f64 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -93,6 +93,8 @@ path: /docs/ecosystem/architecture - title: Installing the Ecosystem on Kubernetes path: /docs/ecosystem/installing/k8s + - title: Managing automated test runs + path: /docs/ecosystem/cps - title: Selecting tests to run in the Ecosystem path: /docs/cli-command-reference/ecosystem-cli-runs-prepare - title: Running tests in the Ecosystem diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md index 64a31561..f6003e32 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md @@ -96,21 +96,21 @@ You can then deploy your Galasa tests to a Maven repository and set up a test st ## Upgrading the Galasa Ecosystem -To upgrade the Galasa Ecosystem to use a newer version of Galasa, for example version 0.29.0, run the following command: +To upgrade the Galasa Ecosystem to use a newer version of Galasa, for example version 0.30.0, run the following command: On Mac or Unix: ``` helm upgrade galasa/ecosystem --reuse-values \ ---set galasaVersion=0.29.0 --wait +--set galasaVersion=0.30.0 --wait ``` On Windows (Powershell): ``` helm upgrade galasa/ecosystem --reuse-values ` ---set galasaVersion=0.29.0 --wait +--set galasaVersion=0.30.0 --wait ``` where:
diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md index 68c0e1d7..e953d4d9 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md @@ -50,10 +50,10 @@ The ecosystem needs to know the hostname or IP address of the VM on which the Do ``` hostname: 192.168.1.87 galasaRegistry: icr.io/galasadev -version: 0.29.0 +version: 0.30.0 engineController: - controllerVersion: 0.29.0 - engineVersion: 0.29.0 + controllerVersion: 0.30.0 + engineVersion: 0.30.0 simplatform: version: 0.15.0 ``` diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md b/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md new file mode 100644 index 00000000..fe3b860e --- /dev/null +++ b/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md @@ -0,0 +1,174 @@ +--- +path: "/docs/ecosystem/cps" +title: "Managing automated test runs" +--- + +[Retrieving properties](#retrieving)
+[Setting properties](#setting)
+[Deleting properties](#deleting)
+ +The ability to retrieve, set, and delete properties held in the Configuration Properties Store (CPS) directly into an Ecosystem by using the Galasa CLI makes it easier for testers to set parameters and credentials on the Ecosystem for tests to read and use at runtime. + +System administrators can use the CLI to set Ecosystem-wide configuration properties after Ecosystem installation. + + +## About the Configuration Properties Store + +Properties in the CPS are dot separated values with lower and upper-case segments that define, for example, endpoint, port, and repository properties. These properties instruct the way in which a Galasa test runs. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. + +The CPS is hosted in the Ecosystem's etcd server, a key-value pair store which also hosts the Dynamic Status Store (DSS) and the Credentials Store (CREDs), maintaining a single source of truth about the status of the ecosystem. For more information see the [Ecosystem Architecture](/docs/ecosystem/architecture) documentation. + + +## Managing CPS properties + +When a test is ready to run in the Ecosystem, you can use the CLI to ensure that the appropriate properties and credentials are installed in the Ecosystem for the test to query and use. There is no need to directly access the etcd server, or the REST service, which would have previously been necessary to achieve the same result. Instead, use the `galasasctl properties get`, `galasasctl properties set`, and `galasasctl properties delete` commands to help you to dynamically manage CPS properties that are stored in the etcd server. + +Most properties that are commonly used in Galasa are held in the `framework` namespace and many of the provided examples use the `framework` namespace. The properties that are typically stored in the `framework` namespace are [test stream](../writing-own-tests/test-streams) properties that are used to help run groups of tests in automation in the Ecosystem. Managers also provide their own configuration properties, for example, the configuration properties of the Docker Manager are held in the `docker` namespace. The `--namespace` flag is mandatory for all `galasasctl properties` commands. + +The example commands assume that `GALASA_BOOTSTRAP` environment variable is set, so the `--bootstrap` flag is not required in the command. + +## Retrieving properties from a namespace + +Use the `galasactl properties get` command to read CPS properties and values from a specified namespace in the Galasa Ecosystem to verify that the properties exist and are set correctly. You can filter the properties that are returned by using the property name (to return a single property), or by using prefixes, suffixes, and infixes to return a subset of properties that match the provided criteria. + + +### Retrieve all properties from a namespace + +To retrieve all properties that are stored in the `framework` namespace, use the following command:

+`galasactl properties get --namespace framework` + + +### Retrieve a single property from a namespace + +To retrieve a specific property from the `framework` namespace, specify the property name in the command by using the `-–name` flag. For example: + +```galasactl properties get --namespace framework --name propertyName``` + + +*Note:* The `-–name` flag cannot be used in conjunction with the `–suffix`, `--prefix`, or `-–infix` flags. + +### Retrieve a subset of properties in a namespace + +To filter the properties that are returned, without specifying the property name, use the `–prefix`, `–suffix`, and ``--infix`` flags. You can specify more than one `--infix` value by using a comma separated list. For example, to return properties in the `docker` namespace that start with `docker`, end with `hostname`, and contain `engine` use the following command: + + +On Mac and Unix: + +``` +galasactl properties get \ +--namespace framework --prefix test --suffix stream --infix batch,production +``` + +On Windows (Powershell): + +``` +galasactl properties get ` +--namespace framework --prefix docker --suffix hostname --infix engine +``` + + +The `--prefix`, `--suffix` and `-–infix` flags can be used together or separately to retrieve all properties that match the provided criteria. + + +For a complete list of supported parameters see the galasactl properties get documentation in the cli repository. + + +### Returned properties + + +Properties are returned in summary format. For example: + +``` +namespace name value +docker docker.engine.LOCAL.hostname 127.0.0.1 +docker docker.engine.REMOTE.hostname 103.67.89.6 + +Total: 2 +``` + +If the property value that is returned is longer than 50 characters, the first fifty characters are displayed, followed by three ellipses (`...`). For example: + +``` +namespace name value +framework test.stream this-value-is-60-characters-long-xxxxxxxxxxxxxxxxx... + +Total: 1 +``` + + +Returned properties are first sorted according to the number of segments in the property name (denoted by the period character (.)), and then in alphabetical order. For example: + +``` +namespace name value +framework framework.test.stream.a.b account1 +framework framework.test.stream.b.c account2 +framework framework.test.stream.a myteststream +framework framework.test.stream bestsofar + +Total: 4 +``` + + +## Setting properties in a namespace + +You can update a property and its value in a namespace by using the `galasactl properties set` command. If the property does not exist in that namespace, the command creates the property. You must provide the namespace, the name of the property, and the value of the property in the command in the following example format: + +```galasactl properties set --namespace namespaceName --name propertyName --value newValue``` + +A success message is displayed when the property is updated or created. + +For a complete list of supported parameters see the galasactl properties set documentation in the cli repository. + +### Examples of setting properties in a namespace + +The [WebAppIntegrationTest](../running-simbank-tests/web-app-integration-test) documentation is designed to help you to understand how to set the properties that enable a local test to run in a Galasa Ecosystem. + +For example, the following CPS properties are set for the Docker Manager when running the `WebAppIntegrationTest` locally: + +``` +docker.dse.engine.PRIMARY=LOCAL +docker.default.engines=LOCAL +docker.engine.LOCAL.hostname=127.0.0.1 +docker.engine.LOCAL.port=2375 +docker.engine.LOCAL.max.slots=10 +``` + +The first component, `docker` indicates the namespace. The upper-case components are used to show which part of the property is dynamic, while the lower case is used to define the static parts. + +You can use the `galasactl properties set` command to update these properties so that the test can run in the Ecosystem. To use a remote server as a Docker Engine, simply change the default engine from LOCAL to REMOTE and specify the appropriate connection details. No change is required to the test code, only to the CPS properties file. + +For example, to change the value of the properties in the `docker` namespace, use the following example commands: + +``` +galasactl properties set --namespace docker --name docker.dse.engine.PRIMARY --value REMOTE +galasactl properties set --namespace docker --name docker.default.engines --value REMOTE +galasactl properties set --namespace docker --name docker.engine.REMOTE.hostname --value 103.67.89.6 +galasactl properties set --namespace docker --name docker.engine.REMOTE.port --value 2987 +galasactl properties set --namespace docker --name docker.engine.REMOTE.max.slots --value 20 +``` + +You can also use `galasactl properties set` command to set a repository, OBR, and test catalog property for a test stream. For example, you can set up a test stream called `EXAMPLE` in the `framework` namespace with the following properties: + +``` +framework.test.streams EXAMPLE +framework.test.stream.EXAMPLE.repo http://hostname/your/maven/repository +framework.test.stream.EXAMPLE.obr mvn:dev.galasa/dev.galasa.examples.obr/0.0.1-SNAPSHOT/obr +framework.test.stream.EXAMPLE.location http:///testcatalog/example +framework.test.stream.EXAMPLE.description "Example Test Stream" +``` + +Tests for the `EXAMPLE` test stream are deployed to the Maven repository that is set for `framework.test.stream.EXAMPLE.repo` and are listed in the test catalog location that is provided in `framework.test.stream.EXAMPLE.location`. + + +## Deleting properties from a namespace + +You can delete a property and its associated value in a namespace by using the `galasactl properties delete` command. You must provide the namespace and the name of the property that you want to delete. For example: + +```galasactl properties set --namespace framework --name propertyName``` + +A success message is displayed when the property is deleted. + +For a complete list of supported parameters see the galasactl properties delete documentation in the cli repository. + + + diff --git a/src/markdown-pages/highlights.md b/src/markdown-pages/highlights.md index cf2f184e..5ddc2c92 100644 --- a/src/markdown-pages/highlights.md +++ b/src/markdown-pages/highlights.md @@ -12,9 +12,23 @@ Post a question or share your experiences with other users in our - 0.29.0 highlights + 0.30.0 highlights