GitOps

It is highly recommended to set up a git repository to manage the Service Schemas. A Git repository allows Service Owners to track changes, request reviews, and obtain approval from team members before applying modifications. 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 directory.

mkdir netorca_services
cd netorca_services
git init

Service Owners can also use NetOrca's Template repository which includes CI/CD scripts for Schema validation and submission. In order to clone and use the template:

git clone https://gitlab.com/netorca_public/serviceowner_template.git
cd serviceowner_template

Api Key Authentication

The CI/CD script requires an environment variable named NETORCA_API_KEY for authentication. In order to create a team and an Api Key, please follow the instruction on API KEY management page.

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'