Get Started

As organizations expand their infrastructure automation, scaling and managing these automations become increasingly complex. NetOrca addresses this challenge by enabling organizations to define and consume all their services as code, regardless of their automation maturity. It provides a unified platform for both service providers and consumers to define services, automate provisioning, declarative consumption, and change management.

Here is an illustration showing how NetOrca connects a simple virtual machine service between a Service Owner and a Consumer:

get_started_simple_2

Get Started as Service Owner

Once automation is in place, the automation teams-referred to as Service Owners-must ensure that these resources and workflows are accessible to internal customers. To achieve this, they need to formalize and structure their automation by defining them as Services.

For each service, the Service Owner must gather specific details and requirements from consumers, following the principles of Infrastructure as Code (IaC). To standardize this process, the automation teams create a JSON schema for each service. This schema serves as the service definition, outlining required inputs, configurations, and dependencies. Once defined, the service schemas are sent to NetOrca.

Setting up a Git repository

Setting up a Git repository to manage the Service Schemas is strongly recommended. NetOrca offers CI/CD scripts for validating and submitting the Service Schemas. Service Owners can clone NetOrca's Template repository. Your git repository structure will look like:

serviceowner_template/  
  ├── .netorca/  
  │    ├── config.yaml  
  │    ├── SchemaTemplate.json  
  └── .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"
  }
}

SchemaTemplate.json

Service Schema definition is basically a JSON Schema. You can find details for the Schema construction in Service Definition. The final Service Schema JSON must be in <service_name\>.json file. Here is an example of a JSON file for a Virtual Machine Service Schema:

File Name: VirtualMachine.json

{
  "title": "Virtual Machine",
  "description": "Schema of a Virtual Machine",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "examples": ["CoreVM1"]
    },
    "cpu": {
      "type": "integer",
      "description": "Number of cpu cores",
      "examples": [4, 8]
    }, 
    "memory": {
      "type": "integer",
      "description": "Memory in GB",
      "examples": [4, 8, 16]
    },
    "gpu": {
      "type": "string",
      "description": "Type of the GPU",
      "enum": ["gpu1", "gpu2"]
    }
  },
  "required": ["name", "cpu", "memory"]
}

.gitlab-ci.yml

NetOrca provides a CI/CD script specifically for Service Schema Submission. When Service Owners include this script in their repository, any push to the main branch will trigger the submission of the Service Schema to NetOrca.

Note: 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.

Get Started as Consumer

Once services are defined, consumers must select the services they need and provide the specific details required for each instance of the service. They gather all these details into a JSON/YAML configuration file called Submission Declaration, which is then submitted to NetOrca.

NetOrca relies on declarative submission, meaning that every submission must include the entire declaration, covering all existing, new, or modified resources. This ensures that NetOrca has a complete view of the desired final state. It automatically detects changes, generates the necessary change instances, and manages the full lifecycle of resources accordingly.

Consumers can submit their declaration using the Submission Builder in the GUI or follow the GitOps workflow where they can track, review and approve every modification.

Submission Builder

The NetOrca GUI offers a Submission Builder page for the consumers. Users can build their declarations using the Submission Builder and submit them directly. Below is a video demonstrating how to submit a sample declaration based on the service created above:

Setting up a Git repository

A submission declaration is essentially a dictionary that can be saved as either a JSON or YAML file. This means that consumers can manage and store their declarations in a Git repository. Consumers can use NetOrca's Template repository which includes CI/CD scripts for validating and submitting the declaration. After cloning, your git repository will look like:

consumer_template/  
  ├── .netorca/  
  │    ├── config.yaml  
  │    ├── app_name.json  
  └── .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: The required keys are netorca_global, base_url, metadata.

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

app_name.yaml

In NetOrca, Service Items are grouped in an Application. Consumers can define multiple Applications in one repository. Each Application declaration must be defined in <application_name>.yaml file.

Here is a sample declaration:

File Name: dev.yaml

---
dev:
  services:
    Virtual Machine:
      - name: vm1
        cpu: 2
        memory: 4
      - name: vm2
        cpu: 2
        memory: 4

For more detail of the structure of the submissions, please refer to Submission page.

.gitlab-ci.yml

NetOrca offers a CI/CD script for submission. When the consumer's repository contains the script, any push to the default branch will automatically triggers the submission to NetOrca.

Change Instance Processing

Whenever a consumer team submits a new declaration, NetOrca compares the submitted declaration with the previously stored version. Based on this comparison, NetOrca determines whether a Change Instance needs to be created. Once a Change Instance is generated, it is the Service Owner’s responsibility to process the change. Service Owners must ensure the consumer’s desired state, as specified in the submission, aligns with the actual infrastructure or service provisioned for their team. Once the requested state has been successfully implemented, the Change Instance can be marked as COMPLETED, confirming to the consumer team that their request has been fulfilled.

Consumers can see the list of change instances by:

GUI

Service Owners can fetch and process the change instances:

GUI

More information on Change Instances generation logic can be found on Change Instance Generation Logic

Consumer amendments

If a consumer needs to modify anything in their infrastructure, they must submit an updated full declaration to NetOrca. This update may trigger the creation of new Change Instances for their service items. These Change Instances are then forwarded to the Service Owners, who are responsible for processing them and applying the necessary updates to the consumer's infrastructure. This cycle repeats with every new consumer submission, ensuring that changes are continuously managed and implemented as needed.

GUI