docs: Add docs on rotating encryption keys and managing secrets

Signed-off-by: Eamonn Mansour <[email protected]>

src/data/nav.yaml

@@ -97,9 +97,9 @@
             - title: Configuring authentication
               path: /docs/ecosystem/ecosystem-authentication
             - title: Configuring an Ecosystem using resource files
-              path: /docs/ecosystem/cps-yaml  
-            - title: Updating credentials in an Ecosystem
-              path: /docs/ecosystem/ecosystem-update-creds 
+              path: /docs/ecosystem/resources-yaml  
+            - title: Managing credentials in an Ecosystem
+              path: /docs/ecosystem/ecosystem-manage-creds 
             - title: Managing configuration properties
               path: /docs/ecosystem/ecosystem-manage-cps              
         - title: Managing tests in a Galasa Ecosystem

src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md

@@ -236,6 +236,40 @@ where:<br>
 - `galasaVersion` is set to the version that you want to use and<br>
 - `<release-name>` is the name that you gave to the Ecosystem during installation
 
+## Rotating Encryption Keys
+
+To maintain the security of your Galasa Ecosystem, you may wish to replace the encryption key being used to encrypt credentials in the Galasa Ecosystem's credentials store with a new encryption key, and re-encrypt all your existing credentials using the new key.
+
+**Before proceeding to rotate encryption keys, it is highly recommended to make a backup of the existing credentials stored in your Galasa Ecosystem by running the following command using the Galasa CLI tool:**
+
+```console
+galasactl secrets get --format yaml > /path/to/backup/file.yaml
+```
+
+**where `/path/to/backup/file.yaml` is either an absolute or relative path of your choice to a file where the backup will be stored.**
+
+For Linux and macOS, you can download and run the <a href=https://github.com/galasa-dev/helm/blob/main/rotate-encryption-keys.sh target="_blank" rel="noopener noreferrer">rotate-encryption-keys.sh</a> script via the command-line to simplify the process of rotating encryption keys and re-encrypting credentials.
+
+This script requires the following command-line utilities to be installed:
+
+- [kubectl](https://kubernetes.io/docs/tasks/tools) (v1.30.3 or later)
+- [galasactl](../cli-command-reference/installing-cli-tool.md) (0.38.0 or later)
+- openssl (3.3.2 or later)
+
+The following flags can be supplied when running the script:
+- `--release-name <name>` **Required**. The helm release name provided when installing the Galasa Ecosystem helm chart (see [Installing your Galasa Ecosystem](#installing-your-galasa-ecosystem))
+- `--namespace <namespace>` Optional. The Kubernetes namespace where your Galasa Ecosystem is installed
+- `--bootstrap <bootstrap-url>` Optional. The bootstrap URL of the Galasa Ecosystem that is being serviced. Not required if the `GALASA_BOOTSTRAP` environment variable is set and is pointing to the correct bootstrap URL. Overrides the existing `GALASA_BOOTSTRAP` environment variable value if set
+
+For example:
+
+```console
+./rotate-encryption-keys.sh --release-name example --namespace galasa-dev
+```
+
+The `rotate-encryption-keys.sh` script will automatically update the current encryption key with a new one, and then restart your Galasa Ecosystem's API and engine controller pods so that they can pick up the new encryption key. After rotating the encryption keys, the script will re-encrypt the existing secrets in your Galasa Ecosystem using the newly activated encryption key.
+
+Once the encryption keys have been rotated and the existing secrets have been re-encrypted, the script will clear the fallback decryption keys list and restart the API and engine controller pods for a final time to keep the Galasa services in sync with the contents of the encryption keys secret.
 
 ### Troubleshooting
 

src/markdown-pages/docs/ecosystem/ecosystem-manage-creds.md

@@ -0,0 +1,156 @@
+---
+path: "/docs/ecosystem/ecosystem-manage-creds"
+title: "Managing credentials in an Ecosystem"
+---
+
+[Setting secrets](#setting-secrets)<br>
+[Getting secrets](#getting-secrets)<br>
+[Deleting secrets](#deleting-secrets)<br>
+
+It is likely that a test will need to pass credentials to the application being tested. For example, as HTTP credentials or as username and password values entered onto a 3270 screen. In a Galasa Ecosystem the credentials store (CREDS), which is hosted in the etcd server, securely provides the credentials (for example, password, username, and personal access token) that are required for a test to run in automation.  
+
+You can set a Username, UsernamePassword, Token, or UsernameToken secret in the CREDS by using the Galasa CLI tool's `secrets` commands. The ability to set these properties means that you can supply test cases with the credentials and tokens that they need to run.
+
+The following examples show how you can update the CREDS, and will refer to credentials as secrets. The example commands that are provided in the following sections assume that the `GALASA_BOOTSTRAP` environment variable is set, so the `--bootstrap` flag is not required in the command.
+
+## <a name="setting-secrets"></a>Creating and updating secrets
+
+The `galasactl secrets set` command can be used to create or update secrets in the CREDS. The command's `--username`, `--password`, and `--token` flags can be used in different combinations to create different types of secret.
+
+Optionally, a description can be provided when setting secrets using the `--description` flag to provide useful information as to what the secrets are used for.
+
+For example, a UsernamePassword secret can be created by supplying `--username` and `--password`:
+
+```
+galasactl secrets set --name SYSTEM1 --username "my-username" --password "my-password" --description "an example secret"
+```
+
+A UsernameToken secret can be created by supplying `--username` and `--token`:
+
+```
+galasactl secrets set --name SYSTEM1 --username "my-username" --token "my-token"
+```
+
+A Token secret can be created by supplying `--token` on its own:
+```
+galasactl secrets set --name SYSTEM1 --token "my-token"
+```
+
+A Username secret can be created by supplying `--username` on its own:
+
+```
+galasactl secrets set --name SYSTEM1 --username "my-username"
+```
+
+Base64-encoded values can be supplied using the `--base64-username`, `--base64-password`, and `--base64-token` flags. These base64 flags can be used with the non-encoded flags described above to supply values in different encoding schemes. However, you cannot provide the same value in multiple encoding schemes (e.g. using `--base64-username` and `--username` in the same command).
+
+For example, to create a UsernamePassword secret where both the username and password are base64-encoded:
+
+```
+galasactl secrets set --name SYSTEM1 --base64-username "my-base64-username" --base64-password "my-base64-password"
+```
+
+To create a UsernameToken secret where only the token is base64-encoded:
+
+```
+galasactl secrets set --name SYSTEM1 --username "my-base64-username" --base64-token "my-base64-token"
+```
+
+Once a secret has been created, you can change the type of the secret by supplying your desired secret type using the `--type` flag. When supplying the `--type` flag, all values for the new secret type must be provided. To find out what secret types are supported, run `galasactl secrets set --help`.
+
+For example, to create a UsernamePassword secret and then change it to a Token secret:
+
+```
+galasactl secrets set --name SYSTEM1 --username "my-username" --password "my-password"
+galasactl secrets set --name SYSTEM1 --token "my-token" --type Token
+```
+
+Updated credentials are now available for a test to run in automation on a Galasa Ecosystem.
+
+For a complete list of supported parameters see the <a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_secrets_set.md" target="_blank" rel="noopener noreferrer">galasactl secrets set</a> documentation in the CLI repository.
+
+## <a name="getting-secrets"></a>Getting secrets
+
+You can use the `galasactl secrets get` command to get secrets stored in the CREDS to verify that the secrets exist and are populated correctly. You can also filter results to retrieve a specific secret by providing its name in `galasactl secrets get` commands.
+
+The following table shows the available output formats that can be provided as part of the `galasactl secrets get` command:
+
+| Name |  Description  |
+| :---- | :-------- | 
+| `--format summary` | The default format is _summary_. Summary format is useful if you need a quick, high-level overview. If you omit the `--format` flag in the command, results are returned in summary format. You can set the summary format explicitly by setting the `--format summary` flag in the `galasactl secrets get` command.   | 
+| `--format yaml` |  The results from `galasactl secrets get` are returned as GalasaSecret resources in YAML format. This YAML content can then be used in `galasactl resources` commands to create, update, and delete secrets using a YAML file. See [Configuring an Ecosystem using resource files](../ecosystem/resources-yaml) for more details.|
+
+For example, you can use the following command to retrieve all secrets in `yaml` format:
+
+```
+galasactl secrets get --format yaml
+```
+
+For a complete list of supported parameters see the <a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_secrets_get.md" target="_blank" rel="noopener noreferrer">galasactl secrets get</a> documentation in the CLI repository.
+
+### Getting all secrets
+
+To retrieve all secrets stored in a Galasa Ecosystem, run the following command:
+```
+galasactl secrets get
+```
+
+This will display the retrieved secrets in a summary format:
+
+```
+name    type             last-updated(UTC)   last-updated-by description
+SIMBANK UsernamePassword 2024-11-01 10:43:06 galasa-user     credentials for simbank
+SYSTEM2 Token            2024-11-01 10:43:41 galasa-user2    example access token
+SYSTEM1 Username         2024-11-01 10:42:46 galasa-user3    example secret
+
+Total:3
+```
+
+### Get a secret by name
+
+To retrieve a secret with a specific name, use the following example command:
+
+```
+galasactl secrets get --name {mysecret}
+```
+
+where `{mysecret}` is the name of the secret that you want to get.
+
+For example, to view a secret named `SYSTEM1`, run the following command:
+
+```
+galasactl secrets get --name SYSTEM1
+```
+
+The following example shows the returned secret:
+
+```
+name    type             description       last-updated(UTC)   last-updated-by
+SYSTEM1 UsernamePassword an example secret 2024-10-30 16:23:49 galasa-user
+
+Total:1
+```
+
+## <a name="deleting-secrets"></a>Deleting secrets
+
+When a secret is no longer used or required by tests, it can be deleted from the Galasa Ecosystem using the `galasactl secrets delete` command, supplying the name of the secret as part of the command.
+
+To delete a specific secret, use the following command:
+
+```
+galasactl secrets delete --name {mysecret}
+```
+
+where:
+`{mysecret}` is the name of the secret that you want to delete.
+
+
+For example, to delete a secret called `SIMBANK`, run the following command:
+
+```
+galasactl secrets delete --name SIMBANK
+```
+
+If the secret does not exist, an error will be displayed to indicate that the secret could not be found.
+
+For a complete list of supported parameters see the <a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_secrets_delete.md" target="_blank" rel="noopener noreferrer">galasactl secrets delete</a> documentation in the CLI repository.