How to Introduce Judge-d in Your Company – A Big Picture
How to Introduce Judge-d in Your Company – A Big Picture
Take Judge-d in broad strokes with this introduction to its components and deployment processes.
Join the DZone community and get the full member experience.Join For Free
This article aims at explaining how Judge-d, an open-source framework for performing contract testing described here, should be introduced in your company. General requirements and all supporting tools are described, giving a big picture of how to use Judge-d. Technical details are omitted whenever possible so that the presented view is not obscure. All required references to more technical sources are provided.
- Deployment of Judge-d server
- Deployment of Judge-d agents
- Introduction of contract generation in all services
- Introduction of contract publication in CI pipeline
- Introduction of contract validation in CI pipeline
- Deployment of Judge-d UI
Deployment of Judge-d Server
Judge-d server is a central place of contract verification as shown above. It needs to be aware of the state of the environments (what services are present) and the contracts of any service which was or is available in any environment. The Judge-d server needs a datastore in order to keep all the required information. The persistence layer of Judge-d is based on Spring Data JPA, allowing it to support relational databases like PostgreSQL. A Docker image of Judge-d server is available on Docker hub.
Deployment of Judge-d Agents
Information about names and versions of all services deployed in each environment is gathered by Judge-d agents. A Judge-d agent collects information about an environment on which it is deployed. Currently, Kubernetes is supported as a source of information – the name and version of a service should be part of a Docker image name used by a pod associated with the service. However, it is easy to add support for other sources like Consul, which is on the roadmap of Judge-d. For example, in HL Tech, each environment is represented by a Kubernetes cluster. In each cluster one Judge-D agent is deployed, which periodically fetches information about the environment set up in this cluster. All agents should be so configured that they send request to previously deployed Judge-d.
Introduction of Contract Generation in All Services
Currently, Judge-d supports validation of REST and JMS contracts, but it was so designed that adding new protocols is as straightforward as possible. When a service should be under Judge-d jurisdiction, it should generate files containing its expectations towards other services (providers) and its capabilities to provide particular functionalities. Expectations and capabilities should be expressed in a format clear for currently implemented Judge-d validators.
REST contracts are expressed in Pact format on the consumer side and in Swagger format on the provider side. Pact files containing REST contracts can be generated using either Pact tests or Pact Gen, which is described in this article and available on the Maven repository. The technical details of how Swagger files are composed can be found in code of Judge-d server. This test uses the fact that this file can be fetched from an endpoint if Swagger is correctly configured for the project. In order to compare expectations expressed in Pact format and capabilities expressed in Swagger format, Atlassian swagger-request-validator-pact is used.
JMS contracts are expressed in Vaunt format on both consumer and provider sides. Vaunt contracts are generated using Vaunt Generator. In order to compare expectations and capabilities expressed in Vaunt format, Vaunt Validator is used. The Vaunt framework is described in this article and is available on the Maven repository.
Introduction of Contract Publication in a CI Pipeline
Judge-d needs to verify beforehand that deployment of a new or changed service would not break its contracts with another service. Therefore, both contract publication and contract verification, described in the subsequent section, must occur before the deployment is performed. In HL Tech, a Jenkins pipeline is used to perform CI. A simplified Jenkins pipeline with contract testing is presented in Picture 2.
There are 2 environments specified – SIT and UAT. Firstly, tests are launched and all required files with contracts for given service are generated. One of next steps must be contract publication. In this step, contracts are taken from file and sent to one of the endpoints exposed by the Judge-d server. In HL Tech, Judge-d Contract Publisher is used. It comes as a Gradle plugin, Maven plugin or in standalone version, all of which are published on Maven repository. Contract publisher must be so configured that it is able to send the contracts to the previously deployed Judge-d server. Judge-d stores the contracts in the database. Critically important is to ensure that contracts of any service deployed in any environment must not be updated or contract validation performed by Judge-d is no longer valid. It is worth mentioning that Judge-d does not prevent this from happening. The main reason for this is that updating contracts of services which are not yet deployed is acceptable for Judge-d.
Introduction of Contract Validation in CI pipeline
Contract validation performed for each environment separately (in the example, for SIT and UAT) must be a step after contract publication takes place and before deployment happens, as shown in the picture above. It requires one REST call to an endpoint exposed by Judge-d. Name and version of the service must be provided along with the environment which should be validated. Judge-d uses validators for any protocol mentioned in the contracts of the service. After validation, a report is returned. It might be parsed and displayed in CI tool (Jenkins in case of HL Tech). If validation indicates that any of the contracts are broken, the pipeline should return an error and, as a result, deployment of the service cannot occur.
Deployment of Judge-d UI
Judge-d is a single source of truth about whole ecosystem. Therefore, it can be used as a tool to provide a clear view of the interrelationship of all microservices deployed in all environments in the whole ecosystem. In order to facilitate. In order to facilitate that functionality, Judge-d UI was developed. It is a standalone component to be deployed using its Docker image.
Judge-d In the Cloud
Judge-d server is deployed in Heroku for demonstration purposes along with Judge-d-ui. After any change is successfully introduced to either Judge-d or its UI, a new deployment on Heroku happens. One step in a Travis pipeline (another CI tool) of Judge-d-ui is launching scripts which automatically generate an environment with the name DEMO with predefined services and subsequently store contracts for some of this services (or all of them). This data is stored in Judge-d server and visualized using Judge-d-ui.
Opinions expressed by DZone contributors are their own.