Get Started

• 1: Install Client
• 2: Install Worker
• 3: Tutorial

1 - Install Client

For testing in the inner dev loop, you can use Skyramp through either our VSCode Extension or our terminal client. This page walks you through installing the terminal client.

For automated testing in CI/CD pipelines, please see the available Skyramp libraries.

Install the Terminal Client

As long as your machine has internet connectivity, you can easily install Skyramp with the following command:

bash -c "$(curl -fsSL https://skyramp.dev/installer.sh)"

Follow the step-by-step instructions in the terminal to complete installation.

Check Installation

Check your installation of Skyramp by running the following command:

skyramp version

For reference, here are all the CLI Commands available.

Uninstalling the Terminal client

If for any reason you want to uninstall Skyramp, run:

/bin/bash -c "$(curl -fsSL https://skyramp.dev/uninstaller.sh)"

Continue to the Walkthrough » for setting up a cloud-native application to try out Skyramp.

2 - Install Worker

The Skyramp Worker acts as the essential foundation for both Mocker, enabling service mocking capabilities, and Tester, facilitating the execution of in-cluster tests.

Prerequisites

If you don’t have Helm installed, refer to Helm’s documentation to get started. Then, follow these two steps to run the Skyramp Worker in Kubernetes using Helm:

1. Install Worker Using Helm

1. Add Skyramp Helm Repo: To access Skyramp’s charts, add the Helm repository:

   helm repo add skyramp https://letsramp.github.io/helm/
   

2. Update Repositories: To ensure you have the latest chart versions, run the following:

   helm repo update
   

3. Install Worker Chart: To deploy the Skyramp Worker application to your Kubernetes cluster, use the following command:

   KUBECONFIG=/path/to/kubeconfig helm install -n <namespace> <release-name> skyramp/worker
   

   • Replace /path/to/kubeconfig with the path to your Kubernetes configuration file (kubeconfig).
   • Replace <namespace> with the Kubernetes namespace where you want to deploy the Skyramp Worker chart. A namespace is a logical grouping of resources within your cluster. You can choose an existing namespace or create a new one.
   • Replace <release-name> with a name for this Helm release. A release is a unique instance of a Helm chart installation. You can choose any meaningful name for this release.

2. Register the Kubernetes Cluster with the Client

To interact with the Worker, you need to register your cluster with the Skyramp Terminal Client:

skyramp cluster register <path to kubeconfig file>

Installing Worker with Python Modules (Optional)

If you need to include additional Python modules in your Skyramp Worker for running dynamic requests and responses, you can follow these steps to build a custom Worker image with the required modules and then deploy it using Kubernetes.

Building the Worker Image with Python Modules

1. Create a Dockerfile in your project directory or modify the existing one if you have it.

   FROM --platform=linux/amd64 public.ecr.aws/j1n2c2p2/rampup/worker:latest
   COPY requirements.txt /
   RUN pip3 install -r /requirements.txt
   

   This Dockerfile uses the base Skyramp Worker image and copies your requirements.txt file into it, then installs the Python modules specified in requirements.txt. Make sure to replace requirements.txt with the actual name of your requirements file.

2. Build the custom Worker image using the docker build command. Replace <image-name> with a suitable name for your custom image and <image-tag> with the desired tag:

   docker build -t <image-name>:<image-tag> .
   

Using the Custom Worker Image

Now that you have built the custom Worker image with your Python modules, you need to push it to a container registry that is accessible to your cluster nodes. Then, you can deploy the Skyramp Worker with the custom image using the following helm install command, overriding the image configuration directly:

KUBECONFIG=/path/to/kubeconfig helm install -n <namespace> <release-name> skyramp/worker --set image.repository=<your-registry>/<image-name>,image.tag=<image-tag>

Continue to How to Mock Services » to learn how to generate and apply service mocks, or to How to Test Services » to learn how to write and start functional and load tests.

3 - Tutorial

This tutorial is designed for developers who are just starting with Skyramp and want to grasp the fundamental concepts of testing and mocking from scratch. Think of it as the “Hello World” for testing and mocking microservices with Skyramp. By the end of this tutorial, you’ll be equipped with the knowledge to seamlessly integrate Skyramp into your own environment.

Note: this tutorial requires a development machine with a terminal client to execute the necessary commands. Skyramp supports Mac, Windows, and Linux environments.

Prerequisites

Before we dive into the tutorial itself, make sure you have the following prerequisites in place on your development machine:

1. Install Docker - Follow these instructions.

You can verify the Docker installation with docker -v:

$ docker -v
Docker version 24.0.6, build ed223bc 

2. Install the Skyramp CLI - Follow these instructions.

You can verify the installation with skyramp version:

$ skyramp version
Skyramp Version:     v0.4.59
Git Commit:          59aed3a
Go Version:          go1.19.2
Default Worker Repo: public.ecr.aws/j1n2c2p2/rampup/worker
Default Worker Tag:  v0.4.59

3. Install Helm - Follow these instructions.

You can verify the Helm installation with helm version:

$ helm version
version.BuildInfo{Version:"v3.13.3", GitCommit:"c8b948945e52abba22ff885446a1486cb5fd3474", GitTreeState:"clean", GoVersion:"go1.21.5"}

4. Install kubectl - Follow these instructions.

You can verify the kubectl installation with kubectl version --client:

$ kubectl version --client
Client Version: v1.29.0
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3

Section 1: Setting Up a Test Environment

The first step for testing and mocking microservices is to set up a test environment. In this section, we will step through using Kubernetes to run a simple service that we can test with Skyramp.

1. Open a terminal client and create a directory on your development machine that will contain the tutorial project. We will use tutorial as our project directory name. In this case, execute these commands:

mkdir tutorial; cd tutorial

2. Next, let’s create a Kubernetes cluster using the Skyramp CLI. You can always register your own Kubernetes cluster with Skyramp, but we’ll create one for the purposes of this tutorial. Simply execute this command in a terminal client:

skyramp cluster create -l

You will see output similar to this:

Creating local cluster     [##############################################################] 100 %
Successfully created local cluster.
Starting/restarting Resolver     [###########################################################] 100 %
Resolver manages DNS changes needed to access the cluster and needs sudo access.
Password:

Provide the password and then set the KUBECONFIG environment variable in the terminal:

export KUBECONFIG=$HOME/.skyramp/kind-cluster.kubeconfig

3. In order install services from Skyramp’s Helm charts, add and update the Skyramp Helm repository using the helm repo command as shown below:

helm repo add skyramp https://letsramp.github.io/helm/; helm repo update

Then, install the echo service into the Kubernetes cluster using helm install:

helm install echo skyramp/echo -n default

The echo service is a simple service that we will use for testing in this tutorial, and can ultimately be substituted by your own services you want to test.

You should see output similar to this:

NAME: echo
LAST DEPLOYED: Thu Jan 11 08:48:55 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=echo,app.kubernetes.io/instance=echo" -o jsonpath="{.items[0].metadata.name}")
  export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT

4. Use kubectl to verify that the echo service was deployed to the cluster and is up and running.

kubectl get pods -n default

You should see output similar to below. Wait to proceed until you see “1/1” in the “READY” column for the service.

NAME                              READY   STATUS    RESTARTS   AGE
echo-cfd9d4bd9-t5vqq              1/1     Running   0          68s

5. Finally, we recommend creating a skyramp subfolder in your project directory to keep all of your Skyramp-related files in an organized location. Of course, this is entirely configurable to your specific needs. For the tutorial, initialize the Skyramp project folder structure with this command:

skyramp init skyramp

This will create a directory called skyramp with several folders underneath. Change the directory to skyramp and list the subdirectories:

cd skyramp; ls

You should now see the following subdirectories for storing your important configuration files:

endpoints mocks responses scenarios targets tests

The skyramp init command can also be used to generate configuration files as templates for tests, mocks, and targets. For more information, check out the Skyramp CLI docs.

Great job! The initial setup for the test environment is now complete.

Section 2: Testing Services with Skyramp’s Tester

Testing is essential to ensure the reliability of your applications. Skyramp simplifies the testing process by providing tools to validate the behavior of your distributed services. In this section, we’ll create a simple test scenario for the echo service.

1. Under the endpoints folder, create a file called echo-endpoint.yaml with these contents:

version: v1
services:
  - name: echo
    alias: echo
    port: 12346
    protocol: rest
endpoints:
  - name: echo-get
    path: /echo/{ msg }
    methods:
      - name: GET
        type: GET
    serviceName: echo

2. Under the scenarios folder, create a file called echo-scenario.yaml with these contents:

version: v1
scenarios:
  - name: echo_test
    steps:
      - requestName: echo_get
      - asserts: requests.echo_get.res.message == "ping pong"
requests:
  - name: echo_get
    endpointName: echo-get
    methodName: GET
    params:
      - name: msg
        in: path
        value: "ping"
    headers:
      key: value

This test scenario will call the echo-get endpoint and pass the value “ping”. The assert will then validate that value returned from the service is “ping pong”.

3. Under the tests folder, create a file called echo-test.yaml with these contents:

version: v1
test:
  name: echo test
  testPattern: 
    - scenarioName: echo_test

4. Notice how the 3 files above relate to each other by endpointName and scenarioName. You should now have this file structure in your project directory:

With the test files in place, let’s run our test scenario using skyramp tester from the command line:

skyramp tester start echo-test -n default

Note: the first time you run the test, the Skyramp Worker will be provisioned and installed to the cluster.

Expected output:

Starting tests
Tester finished
Test echo test------
 [Status: finished] [Started at: 2024-01-11 08:51:26 PST] [End: 2024-01-11 08:51:26 PST] [Duration: 0s]
  - pattern0.echo_test
    [Status: finished] [Started at: 2024-01-11 08:51:26 PST] [Duration: 0.0083s]
  - pattern0.echo_test.0.echo_get
    [Status: finished] [Started at: 2024-01-11 08:51:26 PST] [Duration: 0.0033s]
    Request : {"Path":"http://echo:12346/echo/ping","Method":"GET","Headers":{"key":"***sanitized***"}}
    Response: {"StatusCode":200,"Payload":"{\"message\":\"ping pong\"}"}
  - pattern0.echo_test.1.assert
    [Status: finished] [Started at: N/A]
    Assert: requests.echo_get.res.message == "ping pong"
    Passed: true

Nice work! You’ve successfully created and run a basic test for the echo service using Skyramp. Skyramp can support many types of test scenarios across multiple microservices running in a test environment. From this starting point, you can continue to explore the various ways to enhance the reliability of your applications through testing with Skyramp.

Resources to explore further:

• Tester
• Scenarios and Asserts
• Dynamic Requests
• Load Testing

Section 3: Mocking Services with Skyramp’s Mocker

Mocking is a crucial aspect of testing where we can simulate certain functionality to isolate and test specific components without relying on the actual implementation. Skyramp provides a rich framework for mocking within Kubernetes environments.

1. From the terminal, execute the following to uninstall the running echo service:

helm uninstall echo -n default

Expected output:

release "echo" uninstalled

2. If we run our test scenario again, we see that the service we want to test is not running. So, the output below showing an error with “no such host” is expected.

skyramp tester start echo-test -n default

Expected output:

Starting tests
Tester failed
Test echo test------
 [Status: failed] [Started at: 2024-01-11 09:05:29 PST]
  Error: failed to resolve echo: lookup echo on 10.96.0.10:53: no such host
  - pattern0.echo_test
    [Status: initializing] [Started at: N/A]

3. Let’s proceed by mocking this missing service, which is the echo service. Under the responses folder, create a file called echo-response.yaml with these contents:

version: v1
responses:
  - name: echo_get
    endpointName: echo-get
    methodName: GET
    blob: |
      {
        "message": "ping pong"
      }      

4. Under the mocks folder, create a file called echo-mock.yaml with these contents:

version: v1
mock:
  description: echo mock
  responses:
    - responseName: echo_get

Now your project structure should look like this:

5. We can apply our new mock using skyramp mocker from the command line:

skyramp mocker apply echo-mock -n default

Expected output:

Applying mock config     [##############################################################] 100 %
Successfully applied mock configurations.

6. Run the test scenario again with the mock in place:

skyramp tester start echo-test -n default

We see our test scenario executes and finishes with a passing result:

Starting tests
Tester finished
Test echo test------
 [Status: finished] [Started at: 2024-01-11 08:54:53 PST] [End: 2024-01-11 08:54:53 PST] [Duration: 0s]
  - pattern0.echo_test
    [Status: finished] [Started at: 2024-01-11 08:54:53 PST] [Duration: 0.0015s]
  - pattern0.echo_test.0.echo_get
    [Status: finished] [Started at: 2024-01-11 08:54:53 PST] [Duration: 0.0011s]
    Request : {"Path":"http://echo:12346/echo/ping","Method":"GET","Headers":{"key":"***sanitized***"}}
    Response: {"StatusCode":200,"Payload":"{\"message\":\"ping pong\"}"}
  - pattern0.echo_test.1.assert
    [Status: finished] [Started at: N/A]
    Assert: requests.echo_get.res.message == "ping pong"
    Passed: true

Congratulations! You’ve successfully set up a basic mock using Skyramp.

Resources to explore further:

• Mocker
• Dynamic Responses
• Generate a Mock from User Input
• gRPC Proxying

Section 4: Adapting Skyramp to Your Environment

Now that you’ve grasped the basics of testing and mocking with Skyramp, you can adapt these concepts to your specific environment.

Integrating Skyramp with Your Kubernetes Services

1. Identify the services in your Kubernetes environment that can benefit from testing and mocking.

2. Incorporate testing scenarios like the one in Section 2 to validate the functionality of your services.

3. Follow a similar process to what you’ve learned in Section 3 to create mock descriptions for service dependencies as needed.

Customizing Skyramp Configurations

1. Explore Skyramp’s configuration options to tailor the testing process to your specific needs. Skyramp supports multiple protocols and environment setups.

2. Use skyramp init to create description file templates as a base to work from. These templates provide the many configuration parameters available to you.

Resources to explore further:

• Dashboard
• Architecure
• Libraries
• CLI commands
• YouTube Videos
• Blog Articles