Skip to main content

Java

Latest SDK Version​

0.3.6

Note

Version 0.3+ of this SDK uses V2 of the Signadot API, in which some type and method names have changed. If you're upgrading from an older version, you'll need to update your code to match the new API.

Installation​

The SDK can be added as a dependency to a Java project as follows:

<dependency>
    <groupId>com.signadot</groupId>
    <artifactId>signadot-sdk</artifactId>
    <version>0.3.6</version>
</dependency>

Usage​

Create Sandbox​

Assume a hypothetical Route service in the below example. This Route service is changed and an image corresponding to the new version is built and pushed to the registry. You wish to run integration tests against the new untested version.

// Initialize client
ApiClient apiClient = new ApiClient();
apiClient.setApiKey("my-signadot-api-key");

// A particular service that we want to fork, starting from the specified
// Kubernetes workload of kind "Deployment" called "route" in 
// namespace "hotrod".  To fork an Argo Rollout, use kind "Rollout".
SandboxFork routeFork = new SandboxFork()
    .forkOf(new SandboxForkOf().kind("Deployment").namespace(HOTROD).name("route"))
  
    // customizations to be applied on the fork
    .customizations( 
        new SandboxCustomizations()
            // docker image that the fork should run
            .addImagesItem(new SandboxImage().image("registry/docker-image:tag"))
          
            // any env vars to add / modify
            .addEnvItem(new SandboxEnvVar().name("DEV").value("true")));

// Define the default routegroup, along with the endpoints that we want to expose in order to run
// tests. Here, `http://route.hotrod.deploy:8083` defines it as an endpoint to HTTP port 8083 of
// the forked deployment (and hence `.deploy`) of the `route` service in the `hotrod` namespace.
SandboxDefaultRouteGroup defaultRouteGroup = new SandboxDefaultRouteGroup()
        .addEndpointsItem(new RouteGroupSpecEndpoint().name("hotrod-route").target("http://route.hotrod.deploy:8083"));

// assembling the request to create a sandbox 
Sandbox request = new Sandbox()

    // pass sandbox spec
    .spec(new SandboxSpec()
        .cluster("your-cluster")
        .description("route service test sandbox")
        .addForksItem(routeFork)
        .defaultRouteGroup(defaultRouteGroup));
          
// submitting the request to create sandbox via the API
sandboxApi = new SandboxesApi(apiClient);
Sandbox response = sandboxesApi.applySandbox("org-name", "sandbox-name", request);

You specify one or more forks which are new versions of a particular Microservice. Each fork starts with a particular baseline Deployment running in the Kubernetes cluster and then can have one or more customizations applied to it.

The customizations currently supported are as follows:

  1. docker images
  2. environment variables

Finally, create a request object by setting the sandbox spec comprising cluster name, description, forks and the default routegroup with the endpoint definitions.

Retrieve Endpoint​

The final call above to applySandbox will create the sandbox within the cluster. You use the response and retrieve the specified endpoint URLs to run tests.

List<SandboxEndpoint> endpoints = response.getEndpoints();

// We are interested in the endpoint to the route service we created above. 
// Hence, we find that by endpoint name.
SandboxEndpoint endpoint = null;
for (SandboxEndpoint ep: endpoints) {
    if ("hotrod-route".equals(ep.getName())) {
        endpoint = ep;
        break;
    }
}

// Use this endpoint URL for tests.
// For example, if we are using RestAssured, we may set the baseURI.
RestAssured.baseURI = endpoint.getUrl();

Wait for Readiness​

Before running tests, you need to ensure that the service has come up within the cluster and is ready to take requests.

while (!response.getStatus().isReady()) {
    Thread.sleep(5000);
    response = sandboxesApi.getSandbox(ORG_NAME, "sandbox-name");
}

Run tests​

Once the sandbox is ready, you run tests on the forked service. An example test using RestAssured, a popular framework for writing REST service integration tests is shown below.

@Test
public void testPickupDropOffHasValue() {
    given().
        header("signadot-api-key", SIGNADOT_API_KEY). // API key from Signadot dashboard
        when().
        get("/route?pickup=123&dropoff=456").
        then().
        statusCode(200).
        assertThat().
        body("Pickup", not(emptyOrNullString())).
        body("Dropoff", not(emptyOrNullString()));
}

Delete Sandbox​

Once all the tests are executed and have passed, you delete the sandbox. This will tear down any resources that were set up such a pods, deployments, services etc from the Kubernetes cluster.

sandboxesApi.deleteSandbox("org-name", "sandbox-name");

Additional Resources​