Service Definition
To make a Service available for Consumers on NetOrca, Service Owners must, first, define it using JSON Schema and then publish it on NetOrca.
A Service is defined by a JSON Schema, and a Service Item is essentially a dictionary that can be validated against this Schema.
NetOrca supports JSON Schema V7, with additional NetOrca-specific features that can be integrated into the standard JSON Schema.
Publish a New Service Schema
To publish a new Schema to NetOrca, you need to send a POST HTTP request with the JSON Schema in its body to the Services endpoint:
The primary method to keep and submit the Schemas is via the NetOrca Git process and CI/CD pipelines, where validation will occur on merge request and submission will occur on merges to main branch. With Git and NetOrca's pre-built CI/CD scripts, Service Owners can have more supervision on the changes on Schema and automate the process of publishing them on NetOrca. You can find all the required information to set up a Git repository for the Services in GitOps Page.
Validate Before Service Schema Submission
Before a Service is published onto NetOrca, it should be first sent to NetOrca for validation to ensure it meets the required standards.
This can be done by sending the proposed JSON Schema to /services/validate/ endpoint:
This call will return a response stating whether the Schema is valid or not. If the schema is not valid, NetOrca will respond back with the errors it found.
Update a Service Schema
If the Service Owner already has a Service published in NetOrca and wants to update its schema,
the new modified JSON Schema must be sent to the Services endpoint in the same way as publishing a new Schema.
NetOrca will identify it as a new version of an existing Service by matching the Service name with the title key value in the new Service Schema.
It is also possible to first validate the new updated Schema by sending it to /services/validate/ and then submit it.
README Markdown file for Service
Consumers can view all available Services at once on the Service Catalog page in NetOrca. NetOrca allows Service Owners to publish a README markdown file alongside their Service to provide additional information about each Service. To do so,
It is also possible to put the markdown files in the Services' Git repository and publish them with Services together. You find more details in GitOps Page.
Schema
An example of a Standard JSON Schema is as follows:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/service.schema.json",
"title": "VM",
"description": "Schema of a Virtual Machine",
"type": "object",
"metadata": {},
"properties": {
"name": {
"type": "string",
"description": "The unique identifier for a service item",
"examples": ["CoreVM1"]
}
},
"required": ["name"]
}
title: The title of your Service published in NetOrca- The name of the Service must be unique across all Services of all Service Owners in NetOrca.
- Also, the following titles cannot be used by Service Owners as Service name since they are reserved for Application and Team Metadata which can only be defined by NetOrca admins:
"Application Schema""Team Schema"
description: The description of your Service will be published on Service Catalog pagetype: Since all Service Items declaration must be JSON, the type in first level of a Service schema must be an objectmetadata: is a NetOrca specific field that can be optionally included in Service Schemas to enable certain featuresproperties: is the dictionary of definition of key values required for each Service Item's declarationrequired: is the list of keys defined in properties that are mandatory to present in Service Item's declaration
Unique Identifier
The property name in the Schema serves as the unique identifier for all Service Items within your Service on the NetOrca platform.
As a result, every Service Schema in NetOrca must include a name defined as a required property in the following format:
Service Owners can add regex and length validation if needed.
Metadata
metadata key value is a NetOrca specific json field that can be optionally included in Service Schemas to enable certain features.
The features currently supported are:
Service State
As Consumers begin using a Service, it might not be feasible to decommission that Service immediately. Instead, it is often necessary to first decommission its Service Items and then, if no Consumers remain, gracefully decommission the Service. To facilitate this process, NetOrca provides different states for Services, allowing Service Owners to manage the lifecycle of a Service effectively.
The following are the available states for a Service:
| State | Description |
|---|---|
IN_SERVICE |
This is the default state for a Service. When a Service is in this state, it is fully available. Consumers can create new Service Items, modify, or delete existing ones |
NO_NEW_SERVICE_ITEM |
In this state, the Service is no longer accepting new Service Items. However, Consumers can still modify or delete existing Service Items that were created before the Service entered this state. |
NO_MODIFY_EXISTING_SERVICE_ITEM |
When a Service is in this state, Consumers can only decommission their Service Items |
DECOMMISSIONED |
The Service has been fully decommissioned ano no loger available to the Consumers |
Service Owners can manage the state of their Services in the Schema's metadata:
Tags
As the number of Services in Service Catalogue grows, customers may find it challenging to find the specific Service they need. To address this issue, service tagging is implemented. It gives the ability to Service Owners to group their Services under the same tag, and Consumers search in the Service Catalog by filtering the relevant tags.
A tag is a short string with no space, and it must be lowercase. Each Service can have one or multiple tags. The list of tags can be added to a Service in the Schema's metadata field, e.g.
All tags are accessible by all Services. Service Owners can use the existing tags created by other teams. Also, a new tag will be created automatically if the tag name is not found in the list of all tags. Users can filter the list of Services by searching and selecting the tags in Service Catalog page.References
Service References enables a Service Schema to define a dependency on a Service Item from a different type of Service.
For example, consider a scenario where an organization offers a LoadBalancer and Virtual Machine Services.
The load balancer Service Items must always link to virtual machines that the Consumer owns and that are already in submission declaration.
To facilitate this, the Service Owner of the LoadBalancer Service would specify in their Schema that Consumer must include a reference to the Virtual Machine Service they request Service Items in the same submission.
In this case, the LoadBalancer Service Owner's team would rely on another Service Owner's team to define and provide the Virtual Machine Service.
What happens in NetOrca is that whenever there is any modification in the Consumers referenced Service Items, i.e. in our example Virtual Machine Service Item(s), the main Service Item(s), i.e. in our example LoadBalancerSservice Item, would get a MODIFY Change Instance
Schema Definition
The reference is defined as a property in the Service Schema, and can be either to a single Service Item or a list of Service Items from the same Service. To define reference in the Service Schema,
-
Single Service Item Reference:
-
List of Service Items Reference:
| field | Single Service Item Reference | List of Service Items Reference |
|---|---|---|
type |
"string" |
"array" |
format |
"reference" |
"reference_list" |
reference_method |
"single" |
"list" |
service_reference |
Name of the referenced Service |
Name of the referenced Service |
Consumer's submission example
If the properties above are defined for VM and LoadBalancer services. The Consumer declaration's sample would be
{
"AwesomeCustomer": {
"metadata": {},
"NewApp1": {
"metadata": {},
"services": {
"VM": [
{
"name": "CoreVM1",
"cpu": 2,
"memory": 8
},
{
"name": "CoreVM2",
"cpu": 2,
"memory": 8
}
],
"LoadBalancer": [
{
"name": "CoreLB1",
"load_balancing_method": "round_robin",
"related_vms": ["CoreVM1", "CoreVM2"]
}
],
"NetworkPattern": [
{
"name": "CorePR019",
"pattern_id": "CoreVM2",
"load_balancer": "CoreLB1"
}
]
}
}
}
}