Merge branch 'next' into removeeclipse

src/data/nav.yaml

@@ -93,7 +93,9 @@
             - title: Ecosystem architecture
               path: /docs/ecosystem/architecture
             - title: Installing an Ecosystem using Helm
-              path: /docs/ecosystem/installing/k8s
+              path: /docs/ecosystem/ecosystem-installing-k8s
+            - title: Configuring authentication
+              path: /docs/ecosystem/ecosystem-authentication              
             - title: Test streams
               path: /docs/writing-own-tests/test-streams
             - title: Managing integrated test runs
@@ -104,6 +106,8 @@
               path: /docs/cli-command-reference/ecosystem-cli-runs-prepare
             - title: Running tests in an Ecosystem
               path: /docs/cli-command-reference/ecosystem-cli-runs-submit
+            - title: Retrying and cancelling tests
+              path: /docs/cli-command-reference/runs-reset-cancel
             - title: Viewing test run results 
               path: /docs/cli-command-reference/cli-runs-get
             - title: Downloading test artifacts 

src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md

@@ -50,7 +50,7 @@ In order to run the Galasa SimBanks tests you need to add some configuration inf
 
 The SimBank tests are held in the <a href="https://github.com/galasa-dev/simplatform" target="_blank"> Galasa simplatform repository</a> in GitHub. To start running the tests you need to clone the repository, if you have not already done so. To find out how to clone the cli repository, follow the instruction in the `Launching SimBank` section in the [Exploring Galasa SimBank online](simbank-cli) documentation.
 
-After cloning the repository, complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.25.0` and Galasa uber OBR version `0.31.0`.
+After cloning the repository, complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.25.0` and Galasa uber OBR version `0.32.0`.
 
 You can find the version of the `dev.galasa.simbank.obr` that you are using by looking in the `pom.xml` file in the `dev.galasa.simbank.obr` folder. The `dev.galasa.uber.obr` is the OBR that contains all the bundles that are needed for Galasa to work including Managers, any required dependencies, the framework, etc. The version of the `dev.galasa.uber.obr` depends on which version of Galasa you have installed.
 

src/markdown-pages/docs/cli-command-reference/runs-download.md

@@ -62,7 +62,7 @@ GAL2501I: Downloaded 11 files to folder U5432_2023-05-06_10:30:15
 
 ### Identifying output for test retries
 
-If a test is scheduled to run at a particular time but is unable to start, for example due to a lack of resources that are available in the environment, the ecosystem might retry the test at a later time. When investigating problems with a test running in an ecosystem, it is useful to download the artifacts that are associated with the retries of that test.
+If a test is scheduled to run at a particular time but is unable to start, for example due to a lack of resources that are available in the environment, the Ecosystem might retry the test at a later time. When investigating problems with a test running in an Ecosystem, it is useful to download the artifacts that are associated with the retries of that test.
 
 When using the `runs download` command, if a test has run more than once, a number is added to the folder name to indicate the number of the retry, as shown in the following example:
 

src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md

@@ -0,0 +1,56 @@
+---
+path: "/docs/cli-command-reference/runs-reset-cancel"
+title: "Retrying and cancelling tests"
+---
+
+
+Sometimes tests can become stuck in a loop and fail to finish running, for example, due to a lack of available resources, an environmental problem, or a timeout. You can retry a test to run again by using the `runs reset` command. If the test continues to fail to finish running, you can use the `runs cancel` command to cancel the test. 
+
+Retrying a test sets the status of the test run in the DSS to `queued` status. Cancelling a test removes all entries in the DSS for that test run. For this reason it is preferable to retry a test rather than cancel a test. All information that is stored in the RAS about the test is kept and is not removed when either the `runs reset` or `runs cancel` command is run.
+
+
+You can view the full list of options that are available with the `runs reset` and `runs cancel` commands in the 
+<a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_runs.md" target="_blank">Galasa cli repository</a>.
+
+## Working with the `runs reset` command
+
+The following example retrys a test run called _C1234_ by using the following command: 
+
+```
+galasactl runs reset --name C1234
+```
+
+### Output for test retries
+
+When using the [galasactl runs download](ecosystem-cli-runs-download) command to view test results, if a test has run more than once, a number is added to the folder name to indicate the number of the retry, as shown in the following example:
+
+```
+C1234-1-2023-05-25_18:30:26
+C1234-2-2023-05-25_18:30:26
+C1234-3
+```
+
+In this example, the test _C1234_ tried to run twice unsuccessfully and completed on the third try. The numbers _1_ and _2_ in the folder names of the first two test run attempts indicate the retry order. The inclusion of the timestamp in folder name of the first two tries indicates that the test did not finish running. The third time the test finished running, so no timestamp is included as part of the name of the folder. 
+
+## Working with the `runs cancel` command
+
+The following example cancels a test run called _C1234_ by using the following command: 
+
+```
+galasactl runs cancel --name C1234
+```
+
+All information that is held in the DSS about the test run is removed. A message is returned in the log to say that the test run was lost and results are returned on the terminal in the following example format: 
+
+```
+2024/02/07 13:34:28 Run C1234 was lost - inttests/dev.galasa.inttests/dev.galasa.inttests.core.local.CoreLocalJava11Ubuntu
+submitted-time(UTC) name requestor status result test-name
+
+Total:1 Lost:1
+2024/02/07 13:34:28 GAL1017E: Not all runs passed. 1 failed.
+GAL1017E: Not all runs passed. 1 failed.
+2024/02/07 13:34:28 Exit code is 2
+```
+
+
+

src/markdown-pages/docs/cli-command-reference/runs-submit-local.md

@@ -3,8 +3,11 @@ path: "/docs/cli-command-reference/cli-runs-submit-local"
 title: "Running tests locally using the command line"
 ---
 
+
 The `galasactl runs submit local` command submits tests to run within the local JVM, rather than dynamically deploying the tests to a remotely deployed Galasa Ecosystem. 
 
+You can submit a [Java test](#Java) and a [Gherkin test](#Gherkin) by using the command but must to specify different flags on the command line for each test type. Read on to find out more about how to submit each type of test on your local machine.
+
 Running tests locally should only be used during test development to verify that the test is behaving as expected. 
 Local runs do not benefit from the features that are provided when running tests within a Galasa Ecosystem. For example, resources are not cleaned-up in the event of a failure and scaling capabilities are limited by workstation resources. 
 
@@ -15,8 +18,12 @@ To use the `galasactl runs submit local` command, the `JAVA_HOME` environment va
 
 The level of Java must match the supported level of the Galasa version that is being launched. Use the `galasactl --version` command to find the galasactl tool version. We currently support Java version 11 to version 16 JDK. _Note:_ We do not currently support Java 17 or later.
 
+You can view the full list of options that are available with the `galasactl runs submit local` command in the 
+<a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_runs_submit_local.md" target="_blank">Galasa cli repository</a>.
+
+## <a name="Java"></a>Running a Java test with the `runs submit local` command
 
-Use the following command to run a test in the local JVM.
+Use the following command to run a Java test in the local JVM.
 
 On Mac or Unix:
 
@@ -40,14 +47,45 @@ where:
 - `--obr` specifies where the  CLI tool can find an OBR which refers to the bundle where the tests are stored. When running locally, all tests must exist in the OBR (or OBRs) that are passed to the tool. The `--obr` parameter specifies the Maven co-ordinates of the obr jar file, in the format `mvn:groupId/artifactId/version/classifier`.
 - `--class` specifies which test class to run. The string is in the format of `<osgi-bundle-id>/<fully-qualified-java-class>`. All test methods within the class are run. Use multiple flags to test multiple classes.
 
-You can view the full list of options that are available with the `galasactl runs submit local` command in the 
-<a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_runs_submit_local.md" target="_blank">Galasa cli repository</a>.
+
+## <a name="Gherkin"></a>Running a Gherkin test with the `runs submit local` command
+
+Use the following command to run a Gherkin test in the local JVM. Note that the `--gherkin` flag is specified and that the `--obr` or `--class` flags are not required. 
+
+On Mac or Unix:
+
+```
+galasactl runs submit local --log - \
+--gherkin file:///path/to/gherkin/file.feature
+```
+
+
+On Windows (Powershell):
+
+```
+galasactl runs submit local --log - `   
+--gherkin file:///path/to/gherkin/file.feature
+```
+
+where:
+
+- `--log` specifies that debugging information is directed somewhere, and the `-` means that it is sent to the console (stderr).
+- `--gherkin` specifies the path where the  CLI tool can find the Gherkin file containing the Gherkin tests. The path must be specified in a URL form, ending in a `.feature` extension. For example,`file:///Users/myuserid/gherkin/MyGherkinFile.feature` or `file:///C:/Users/myuserid/gherkin/MyGherkinFile.feature`.
+
+
+Examples of Galasa Managers in GitHub that have Gherkin support currently available are the <a href="https://github.com/galasa-dev/managers/tree/main/galasa-managers-parent/galasa-managers-core-parent/dev.galasa.core.manager/src/main/java/dev/galasa/core/manager/internal/gherkin" target="_blank">
+Core Manager</a>, and the <a href="https://github.com/galasa-dev/managers/tree/main/galasa-managers-parent/galasa-managers-zos-parent/dev.galasa.zos3270.manager/src/main/java/dev/galasa/zos3270/internal/gherkin" target="_blank">
+zos3270Terminal Manager</a>. For more information about these Managers, see the [Manager](../managers) documentation section. 
+
+
+
+For more information about Gherkin, see the <a href="https://cucumber.io/docs/guides/overview/" target="_blank">Cucumber website.</a>
 
 ## Overriding the path to the default local Maven repository
 
 In order to run, tests require compiled artifacts to be hosted in a Maven repository. The artifacts must be bundled as an OSGI bundle. When you build a Galasa project locally, the built artifacts are placed by default in the `~/.m2/` repository in your home directory; the default location of the local Maven repository.  
 
-If you want to use a non-standard location for your local Maven repository when running a test locally, rather than the default `~/.m2/` repository, you can specify the path to your non-standard local Maven repository folder when launching a test by setting the  `--localMaven` flag on the `galasactl runs submit local` command. The `--localMaven` parameter tells the CLI tool where Galasa bundles can be loaded from on your local file system. The parameter value must be given in a URL form, for example, `file:///Users/myuserid/mylocalrepository` or `file://C:/Users/myuserid/mylocalrepository`.
+If you want to use a non-standard location for your local Maven repository when running a test locally, rather than the default `~/.m2/` repository, you can specify the path to your non-standard local Maven repository folder when launching a test by setting the  `--localMaven` flag on the `galasactl runs submit local` command. The `--localMaven` parameter tells the CLI tool where Galasa bundles can be loaded from on your local file system. The parameter value must be given in a URL form, for example, `file:///Users/myuserid/mylocalrepository` or `file:///C:/Users/myuserid/mylocalrepository`.
 
 *Note:* the repository that is referenced by the `--localMaven` flag must contain the test, Manager, and Galasa framework OBRs (OSGi Bundle Repositories) that the test needs in order to run. Galasa uses OBRs to locate tests in the specified Maven repository, along with all of the Managers that the test requires.
 

src/markdown-pages/docs/ecosystem/ecosystem-architecture.md

@@ -22,7 +22,7 @@ The following diagram highlights a some of the key components that make up the G
 | **Configuration Property Store**                       | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. *Note:* As IP addresses and ports of test machines are stored within the CPS on a users system, we recommend that hard drive encryption is turned on in the operating system where possible.        |
 | **Dynamic Status Store**               | The dynamic status store (DSS) provides status information about the ecosystem and the tests that are running. The DSS is used by the resource manager and engine controller to ensure the limits that are set in the CPS configuration are not exceeded. DSS property values change dynamically as tests are run, showing the resources that are currently being used, shared or locked by a test, so that workloads can be limited to avoid throttling. When running in automation, the DSS is shared by every instance of the framework.                                                             |
 | **Result Archive Store**                      | The result archive store (RAS) is a single database which stores all elements of a test, including the test results, run logs, and test artifacts. These elements can be used to help diagnose the cause of any failures encountered as a result of running a test, or to gather information about a test.  Storing all of this information in one place makes it simple for entire teams to view results.                              |
-| **Credentials Store**                   | The credentials store (CREDs) securely provides the credentials, for example, password, username and authentication token that are required for a test to run in automation. The CREDs is hosted in the etcd server.    |
+| **Credentials Store**                   | The credentials store (CREDs) securely provides the credentials, for example, password, username and personal access token that are required for a test to run in automation. The CREDs is hosted in the etcd server.    |
 | **etcd**                       | The etcd server is a highly available key-value pair store which hosts the Configuration Property Store (CPS), the Dynamic Status Store (DSS) and the Credentials Store (CREDs). The etcd server stores and maintains a single, consistent source of the truth about the status of the ecosystem at any given point in time.      |
 | **CouchDB**                       | This database runs inside Docker container or Kubernetes pod and contains the Result Archive Store (RAS).        |
 

src/markdown-pages/docs/ecosystem/ecosystem-authentication.md

@@ -0,0 +1,33 @@
+---
+path: "/docs/ecosystem/ecosystem-authentication"
+title: "Configuring authentication"
+---
+
+Before interacting with a Galasa Ecosystem using the Galasa command line tool (galasactl), you must be authenticated with it. Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem provided by the `GALASA_BOOTSTRAP` environment variable or through the `--bootstrap` flag.
+
+
+Personal access tokens are stored in the `GALASA_TOKEN` property in the `galasactl.properties` file in your Galasa home folder. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user. 
+
+
+If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is only valid for that session.
+
+## Authentication architecture
+
+The following diagram shows the architecture for the authentication process:
+
+![Galasa ecosystem architecture:](ecosystem-cluster-auth.svg)
+
+
+When a user logs into the Galasa Web UI via their browser, the Web UI contacts the Galasa API server which in turn talks to a Dex server, providing it with the user ID. The Dex server talks to an identity provider, for example GitHub or LDAP, to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to Galasa API server. The token is then sent to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to log into a Galasa Ecosystem. 
+
+On a successful login, a `bearer-token.json` file is created in the Galasa home directory. This file contains a bearer token that galasactl uses to authenticate requests when communicating with a Galasa Ecosystem. If the bearer token expires, galasactl automatically attempts to re-authenticate with the Galasa Ecosystem using the properties in the `galasactl.properties` file within the Galasa home directory. 
+
+### Logging in to a Galasa Ecosystem using the auth login command
+
+You can log in to a Galasa Ecosystem explicitly by using the `galasactl auth login` command. You might want to do an explicit log in if you are running galasactl as part of a build pipeline, or if you just want to make sure you can log in.
+
+
+### Logging out of a Galasa Ecosystem using the auth logout command
+
+To log out of a Galasa Ecosystem using galasactl, you can use the `galasactl auth logout` command. If you run a galasactl command that interacts with an Ecosystem while logged out, galasactl will attempt to automatically log in using the properties in your `galasactl.properties` file within your Galasa home directory.
+