GitOps

It is highly recommended to set up a git repository to manage the Service Schemas. A Git repository allows the Service Owners to track the changes to their service schemas, request reviewing and approving of any modifications from other team members before submission. Therefore, they can have more supervision on their Schemas. NetOrca provides CI/CD scripts for validating and submitting the Service Schema. So, as soon as Service Owners push new commits or merge their Merge Requests, their Services will be updated immediately on NetOrca.

Set Up Repository

Create a directory where you want to keep all files regarding your Service Schemas, and then initialize a git repository inside the repository.

Repository Structure

The following is an overview of the Service Owner's git repository structure:

git_root_directory/
  ├── .netorca/
  │   ├── config.yaml
  │   ├── <service_1_name>.json
  │   ├── <service_1_name>.md
  │   ├── <service_2_name>.yaml
  │   └── <service_2_name>.md
  └── .gitlab-ci.yml

config.json

This file contains the NetOrca base url. Here is an example of a config.json file:

{
  "netorca_global": {
    "base_url": "https://api.netorca.io/v1"
  }
}

In this file, netorca_global and base_url are the required keys.

<service_name>.json

Service Schema definition is basically a JSON Schema. You can find all detail for defiling the Schema in Service Definition. The final Service Schema JSON must be put in <service_name\>.json file. Here is an example of a JSON file for VM Service:

File Name: VM.json

{
  "$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"]
    },
    "cpu": {
      "type": "integer",
      "examples": [4, 8]
    }, 
    "memory": {
      "type": "integer",
      "examples": [4, 8, 16]
    }
  },
  "required": ["name", "cpu", "memory"]
}

<service_name>.md

As it is mentioned in README Markdown file for Service, Service Owners have the option to include a markdown file with their services to provide additional details. These markdown files can also be stored in the Git repository. NetOrca's CI/CD script identifies each service's markdown file by matching the service definition file name with the corresponding markdown file.

For the example service above the markdown file could be:

File Name: VM.md

# Virtual Machine Service

This a README file to explain more the VM service...

.gitlab-ci.yml

NetOrca provides a CI/CD script specifically for Service Validation and Submission. When Service Owners include this script in their repository, any push to the default branch (e.g., main or master) will trigger an automatic submission of the Service Schema definition to NetOrca. For other branches, the Schema will be sent to NetOrca for validation.

Below is the CI/CD script to be used in a GitLab repository:

stages:
  - validate
  - submit

image: python:3.10-buster
before_script:
  - pip install -q --upgrade pip
  - pip install -q netorca-sdk

validate:
  stage: validate
  variables:
    NETORCA_VALIDATE_ONLY: "True"
  script:
    - wget -q 'https://netautomate.gitlab.io/netorca_tools/cicd/latest/serviceowner_submission.py'
    - python serviceowner_submission.py
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

submit:
  stage: submit
  variables:
    NETORCA_VALIDATE_ONLY: "False"
  script:
    - wget -q 'https://netautomate.gitlab.io/netorca_tools/cicd/latest/serviceowner_submission.py'
    - python serviceowner_submission.py
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

include:
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'