GitOps

A Submission declaration is essentially a dictionary that can be saved as either a JSON or YAML file. This means that consumers can track and store their declarations in a Git repository. Utilizing Git offers several advantages. For instance, consumers can maintain a complete history of all changes made to their declarations. For each submission, they can create a Merge Request, allowing for the review and approval of any modifications.

Set Up Repository

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

mkdir consumer_infrastructure
cd consumer_infrastructure
git init

Consumers can also use NetOrca's Template repository which includes CI/CD scripts for validating and submitting the declaration. In order to clone and use the template:

git clone https://gitlab.com/netorca_public/consumer_template.git
cd consumer_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 Consumer's git repository:

git_root_directory/
  ├── .netorca/
  │   ├── config.yaml
  │   ├── <application_name>.yaml
  │   └── <application_name>.yaml
  └── .gitlab-ci.yml

config.yaml

This file contains the Team Metadata and the NetOrca base url. Here is an example of a config.yaml file:

---
netorca_global:
  base_url: https://api.netorca.io/v1
  metadata:
    budget_code: 12345
    team_name: alpha
    email: alpha@mail.com

In this file, netorca_global, base_url, and metadata are mandatory keys. The metadata for the team is a dictionary specified by the consumer. NetOrca Admin may require consumers to include mandatory data in their metadata; otherwise, a validation error will occur. In the example above, the consumer's metadata would be:

{
  "budget_code": 12345,
  "team_name": "alpha",
  "email": "alpha@mail.com"
}

<application_name>.yaml

In NetOrca, Service Items are defined within an Application. Consumers can define multiple applications in one submission. Each application must be defined in <application_name>.yaml file.

Here is the template of each application yaml file:

File Name: <application_name>.yaml

---
<application_name>:
  metadata:
    key: value
  services:
    <service_1_name>:
      - name: <service_item_name>
        key: value
      - name: <service_item_name>
        key: value
    <service_2_name>:
      - name: <service_item_name>
        key: value
      - name: <service_item_name>
        key: value

Example

Considering the following services defined in NetOrca Catalog by Service Owners:

VM:
    name: str
    cpu: int
    ram: int
LoadBalancer:
    name: str
    algorithm: str

A full example of an application yaml file would be:

File Name: AwesomeApplication.yaml

---
AwesomeApplication:
  metadata:
    application_ci: CI123456
    env: dev
  services:
    VM:
      - name: CoreVM1
        cpu: 4
        memory: 8
      - name: CoreVM2
        cpu: 2
        memory: 4
    LoadBalancer:
      - name: CoreLB1
        algorithm: round-robin

.gitlab-ci.yml

NetOrca offers a CI/CD script for both validation and submission. When this script is included in the consumer's repository, any push to the default branch (e.g., main or master) will automatically submit the declaration to NetOrca. For other branches, the declaration will only be sent to NetOrca for validation.

Below is the CI/CD script to be utilized 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/dev/consumer_submission.py'
    - python consumer_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/dev/consumer_submission.py'
    - python consumer_submission.py
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

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