chore(docs): adding recipe on how to use secrets (#3889)

* chore(docs): adding recipe on how to use secrets * add example * undoing testkube doc change * undoing testkube doc change (again) * docs(cicd): review secrets --------- Co-authored-by: Adnan Rahic <[email protected]>
kubeshop · Jun 4, 2024 · b7cd614 · b7cd614
1 parent f68fd04
commit b7cd614
Show file tree

Hide file tree

Showing 34 changed files with 7,174 additions and 1 deletion.
diff --git a/docs/docs/ci-cd-automation/github-actions-pipeline-with-secrets.mdx b/docs/docs/ci-cd-automation/github-actions-pipeline-with-secrets.mdx
@@ -0,0 +1,266 @@
+---
+id: github-actions-pipeline-with-secrets
+title: Github Actions Pipeline with Secrets
+description: Quick start how to configure one repository to use Tracetest and Github Action with Secrets to run trace-based tests
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
+
+:::note
+[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-with-github-action-and-secrets)
+:::
+
+[Tracetest](https://tracetest.io/) is a testing tool based on [OpenTelemetry](https://opentelemetry.io/) that allows you to test your distributed application. It allows you to use data from distributed traces generated by OpenTelemetry to validate and assert if your application has the desired behavior defined by your test definitions.
+
+
+[Github Actions](https://github.com/features/actions) is a continuous integration/continuous deployment (CI/CD) automation service provided by GitHub. It allows developers to automate their software workflows directly in their GitHub repositories. These workflows can include building, testing, and deploying applications, as well as many other tasks. Workflows are defined using YAML files and can be triggered by various GitHub events such as push, pull requests, or issue comments.
+
+## Running trace-based test in Github Actions with Secrets
+
+When creating CI test scripts in GitHub, you sometimes need to use sensitive information, like passwords and API Keys. To keep this information safe, GitHub provides a feature called [Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). Secrets are encrypted environment variables that you create in a repository and are available to use in your workflows.
+
+In this example, you will see how to configure a repository to use Tracetest and Github Actions with Secrets to run trace-based tests, keeping your sensitive information safe.
+
+Let's start by using a mini Payment ecosystem with 4 APIs that work together to emulate a Payment system.
+
+- **Gateway API**: User-facing API that receives payment orders, protected with Basic Auth.
+- **Payment Executor API**: Executes a payment order after analyzing the customer profile.
+- **Risk Analysis API**: Analyzes a user profile to understand its score.
+- **Wallet API**: Retains data about the Wallet balance of each user.
+
+These APIs are instrumented with [OpenTelemetry SDKs](https://opentelemetry.io/docs/languages/) and send data to [Jaeger](https://www.jaegertracing.io/) via the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/).
+
+```mermaid
+flowchart LR
+    Gateway["Gateway API"]
+    PaymentExecutor["Payment Executor API"]
+    RiskAnalysis["Risk Analysis API"]
+    Wallet["Wallet API"]
+    OTelCollector["OTel Collector"]
+    Jaeger
+    User
+
+    User -- calls --> Gateway
+    subgraph PaymentSystem
+        Gateway -- queries --> Wallet
+        Gateway -- perform order --> PaymentExecutor
+        PaymentExecutor -- queries --> RiskAnalysis
+    end
+    PaymentSystem -- send telemetry --> OTelCollector
+    OTelCollector --> Jaeger
+```
+
+Each one of these APIs has their code specified inside our source code on GitHub ([here](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-with-github-action-and-secrets)) inside the `services` folder.
+
+:::info
+[View the full example code of each API on GitHub, here.](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-with-github-action-and-secrets)
+:::
+
+You can run them together using Docker Compose along with a Tracetest Agent, that we will use soon to test these services, with the following command:
+
+```bash
+git clone [email protected]:kubeshop/tracetest.git
+cd ./tracetest/examples/tracetest-with-github-action-and-secrets
+TRACETEST_API_KEY=<your-agent-key> docker compose up
+```
+
+To run a test, you need execute an API call against the Gateway API. It's protected with Basic Auth.
+
+In this tutorial, you will use a Github Secret to store the Basic Auth credentials and use it in our Github Action workflow by adding it to a [VariableSet](/concepts/variable-sets.mdx) as a secret.
+
+## Creating a GitHub Actions Workflow
+
+To test this recipe, create a repository in your machine, add it to GitHub, and run the workflow. 
+
+### Creating the API Services GitHub Repo
+
+First of all, you need to create a new folder on your machine to store the service code and the repository code. You can do this by running the following commands:
+
+```sh
+# sandbox folder to store our files
+mkdir github-actions-test
+cd ./github-actions-test
+
+mkdir my-repository
+cd ./my-repository
+```
+
+Now copy the code of the Payment Ecosystem to this repository. You can do this by running the following commands:
+
+```sh
+cd ..
+
+git clone [email protected]:kubeshop/tracetest.git
+cp -r ./tracetest/examples/tracetest-with-github-action-and-secrets/services ./my-repository
+
+cd ./my-repository
+
+# remove the .git folder to start a new repository
+rm -rf .git
+git init
+
+git add .
+git commit -m "Initial commit"
+```
+
+Then, [create a new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories#create-a-repository) on GitHub and perform the commands below:
+
+:::note
+Remember to replace `<your-github-user>` and `<your-github-name>` with your Github user and the name of the repository you created.
+:::
+
+```sh
+git remote add origin https://github.com/<your-github-user>/<your-github-name>.git
+git push origin main
+```
+
+After that, you need to configure a new environment on [Tracetest](http://app.tracetest.io) with [these instructions](/concepts/environments.mdx) and generate an environment token for it ([here](/concepts/environment-tokens.mdx)). Remember to store the API Key generated for the Tracetest Agent and the environment token as they will be used on next step.
+
+You need to register three secrets in your GitHub repository using [these instructions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository):
+- `TRACETEST_API_KEY`: that is the API key used by your [agent](/concepts/agent.mdx) to connect to Tracetest
+- `TRACETEST_CLI_TOKEN`: an [environment token](/concepts/environment-tokens) used by the CI to run a test
+- `API_SECRET_PASSWORD`: the password used to authenticate on the Gateway API. For demo purposes, its value is `supersecret`.
+
+
+### Creating the GitHub Actions Workflow
+
+Now that you have the repository set, let's create a new Github Actions workflow file in your repository. First, create a new file in the `.github/workflows` folder with the following content:
+
+```yaml
+name: Run trace-based tests
+
+on:
+  # runs on every push to main
+  push:
+    branches: [main]
+
+  # allows run manually via Actions tab on Github
+  workflow_dispatch:
+
+env:
+  TRACETEST_API_KEY: ${{secrets.TRACETEST_API_KEY}}
+
+jobs:
+  run-trace-based-tests:
+    name: Run trace based tests for Payment Ecosystem
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      # more steps to add
+```
+
+This file defines a workflow that runs on every push to the `main` branch and can be manually triggered via the Actions tab on GitHub. It also defines an environment variable `TRACETEST_API_KEY` that is set to the value of the secret `TRACETEST_API_KEY`. This value will be used by the Tracetest Agent defined inside our `docker-compose.yml` file. The file also adds the first step that checks out the repository code into the CI container.
+
+The next step that you will add is to install the Tracetest CLI in the CI container with the [Tracetest Github Action](https://github.com/kubeshop/tracetest-github-action) and configure the CLI. You can do this by adding the following step:
+
+```yaml
+# ...
+    steps:
+      # previous steps ...
+
+      - name: Configure Tracetest CLI
+        uses: kubeshop/tracetest-github-action@v1
+        with:
+          token: ${{secrets.TRACETEST_CLI_TOKEN}}
+
+      # more steps to add
+```
+
+Then, the two following steps will start the APIs locally using Docker Compose and configure Tracetest Agent to read traces from the Jaeger instance running inside of the Docker Compose network:
+
+```yaml
+# ...
+    steps:
+      # previous steps ...
+
+      - name: Run APIs locally with docker compose
+        run: |
+          docker-compose up -d
+          docker compose logs -f > /tmp/docker-log &
+
+      - name: Configure Tracing Backend
+        run: |
+          tracetest datastore apply --file ./tracing-backend.yaml
+
+      # more steps to add
+
+```
+
+Now, you will set up a [VariableSet](/concepts/variable-sets) with the id `tracetesting-vars` that will have all variables used in your test context, including the `API_SECRET_PASSWORD` secret. This will make Tracetest understand that this variable is a secret and should not be presented on the UI and CLI outputs. You can do this by adding the following step to the workflow file:
+
+```yaml
+# ...
+    steps:
+      # previous steps ...
+
+      - name: Inject secrets as a variable set in Tracetest
+        run: |
+          cat << EOF > vars.yaml
+          type: VariableSet
+          spec:
+            id: tracetesting-vars
+            name: AuthKeys for test
+            description: Variables used in basic auth for my API
+            values:
+            - key: USER
+              value: admin
+            - key: PASSWORD
+              value: ${{secrets.API_SECRET_PASSWORD}}
+              type: secret
+          EOF
+
+          tracetest apply variableset --file ./vars.yaml
+
+      # more steps to add
+```
+
+Finally, you will run the test using the Tracetest CLI, passing the `tracetesting-vars` Variable Set with the `--vars` argument and the test file `trace-based-test.yaml` that contains the test definition. You can do this by adding the following step to the workflow file:
+
+```yaml
+# ...
+    steps:
+      # previous steps ...
+
+      - name: Run trace-based tests
+        run: |
+          tracetest run test --vars tracetesting-vars --file ./trace-based-test.yaml
+
+      # more steps to add
+```
+
+You can run the test by pushing a new commit to the `main` branch with:
+
+```sh
+# assuming that you are on "my-repository" folder
+
+git add .
+git commit -m "Add Tracetest Github Action workflow"
+git push origin main
+```
+
+After a while, you can go to the "Actions" on Github and see the workflow running, as shown below.
+
+![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1717457464/docs/github-action-screenshot_xb2bwj.png)
+
+Drill down to see the jobs contained in this workflow.
+
+![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1717457464/docs/github-action-steps_ji02ev.png)
+
+You can also see the execution of this workflow.
+
+![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1717457464/docs/github-action-running-step_w9supy.png)
+
+Once it's finished, you can see the results of the test in the Tracetest Web UI by going to your environment on [app.tracetest.io](https://app.tracetest.io) and clicking on "Runs".
+
+## Learn More
+
+Please visit our [examples in GitHub](https://github.com/kubeshop/tracetest/tree/main/examples) and join our [Slack Community](https://dub.sh/tracetest-community) for more info!
diff --git a/docs/docs/ci-cd-automation/overview.mdx b/docs/docs/ci-cd-automation/overview.mdx
@@ -16,6 +16,7 @@ This section contains a general overview of running Tracetest in CI/CD pipelines
 You can find guides for:
 
 - [GitHub Actions](/ci-cd-automation/github-actions-pipeline)
+- [GitHub Actions with Secrets](/ci-cd-automation/github-actions-pipeline-with-secrets)
 - [Testkube](/ci-cd-automation/testkube-pipeline)
 - [Tekton](/ci-cd-automation/tekton-pipeline)
 

diff --git a/docs/docs/examples-tutorials/recipes.mdx b/docs/docs/examples-tutorials/recipes.mdx
@@ -125,6 +125,7 @@ This integration point uses the OpenTelemetry Collector as a router to send trac
 These guides show integrations with CI/CD tools.
 
 - [GitHub Actions](/ci-cd-automation/github-actions-pipeline)
+- [GitHub Actions with Secrets](/ci-cd-automation/github-actions-pipeline-with-secrets)
 - [Testkube](/ci-cd-automation/testkube-pipeline)
 - [Tekton](/ci-cd-automation/tekton-pipeline)
 

diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-signoz-pokeshop.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-signoz-pokeshop.mdx
@@ -124,7 +124,7 @@ This will start the Pokeshop Demo app, SigNoz, OpenTelemetry Collector, and Trac
 
 1. Open [Tracetest](https://app.tracetest.io/)
 2. [Configure SigNoz as a tracing backend](/configuration/connecting-to-data-stores/signoz) if you have not already as explained above.
-3. Start creating tests! Make sure to use the `http://demo-api:8081/pokemon/import` URL in your test creation. 
+3. Start creating tests! Make sure to use the `http://demo-api:8081/pokemon/import` URL in your test creation.
 4. To trigger tests in the CLI, first [install the CLI](/cli/cli-installation-reference), [configure it](/cli/configuring-your-cli), and [run a test](/cli/running-tests). From the root of the quick start directory, run:
 
 ```bash

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -446,6 +446,11 @@ const sidebars = {
           id: "ci-cd-automation/github-actions-pipeline",
           label: "GitHub Actions Pipeline",
         },
+        {
+          type: "doc",
+          id: "ci-cd-automation/github-actions-pipeline-with-secrets",
+          label: "Github Actions Pipeline with Secrets",
+        },
         {
           type: "doc",
           id: "ci-cd-automation/testkube-pipeline",

diff --git a/examples/tracetest-with-github-action-and-secrets/.gitignore b/examples/tracetest-with-github-action-and-secrets/.gitignore
@@ -0,0 +1 @@
+.env
diff --git a/examples/tracetest-with-github-action-and-secrets/README.md b/examples/tracetest-with-github-action-and-secrets/README.md
@@ -0,0 +1,36 @@
+# Running Tracetest with secrets on Github Actions
+
+This example shows how you can run Tracetest injecting secrets in a Github Action pipeline.
+
+We are testing an example Payment ecosystem with [Tracetest](https://tracetest.io/), through the main CI script can be seen on [run-trace-based-tests.yml](./githubworkflows/run-trace-based-tests.yml) that could be put under `.github/workflows` folder in your repository
+This script executes a trace-based test that will call the user-facing API with basic auth (that is stored in a Github Secret) and validates if every internal service is properly working.
+
+## Application to be tested
+
+We are testing four APIs that work together to emulate a Payment system. There are 4 APIs:
+- [Gateway API](./services/gateway-api): user-facing API that receives payment orders, protected with Basic Auth
+- [Payment Executor API](./services/payment-executor-api): executes a payment order after analyzing the customer profile
+- [Risk Analysis API](./services/risk-analysis-api): analyze user profile to understand its score
+- [Wallet API](./services/wallet-api): retains data about the Wallet balance of each user
+
+These APIs are instrumented with [OpenTelemetry SDKs](https://opentelemetry.io/docs/languages/) and send data to [Jaeger](https://www.jaegertracing.io/) via the [OTel Collector](https://opentelemetry.io/docs/collector/).
+
+```mermaid
+flowchart LR
+    Gateway["Gateway API"]
+    PaymentExecutor["Payment Executor API"]
+    RiskAnalysis["Risk Analysis API"]
+    Wallet["Wallet API"]
+    OTelCollector["OTel Collector"]
+    Jaeger
+    User
+
+    User -- calls --> Gateway
+    subgraph PaymentSystem
+        Gateway -- queries --> Wallet
+        Gateway -- perform order --> PaymentExecutor
+        PaymentExecutor -- queries --> RiskAnalysis
+    end
+    PaymentSystem -- send telemetry --> OTelCollector
+    OTelCollector --> Jaeger
+```