Skip to content

Submission

Basic Submission

Consumers can request their required resources declaratively. All the desired services must be defined in a single JSON dictionary and submitted to NetOrca. NetOrca then processes the declaration by identifying changes compared to the previous declaration and generating the corresponding change instances. These change instances are subsequently received and processed by the Service Owners.

Important: NetOrca relies on declarative submission. Meaning that, in every submission, the full declaration must be submitted, including all existing, new, or modified resources. NetOrca automatically detects changes, generates the necessary change instances, and manages the lifecycle of your resources. Always ensure your declarations are complete and accurately reflect your final desired resource configurations before submitting them to NetOrca.

Validation and Submission

NetOrca allows consumers to validate their new declaration before submission. This ensures the new declaration is valid and lets consumers anticipate the generated change instances without any effect on the current state of the existing resources. Here's how to validate a declaration before submission:

POST /v1/orcabase/consumer/submissions/validate/ HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY>
{ declaration ... }

After that, when the declaration is ready, it can be submitted to NetOrca:

POST /v1/orcabase/consumer/submissions/submit/ HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY>
{ declaration ... }

The structure of the HTTP requests are the same. The only difference between submitting and validating is the endpoints.

  • The validation endpoint: /v1/orcabase/consumer/submissions/validate/
  • The submission endpoint: /v1/orcabase/consumer/submissions/submit/

Declaration Structure

The declaration is a JSON dictionary that specifies the required resources and their configurations. The declaration must be located in the body of the validation/submission HTTP request. Below is a template of a declaration dictionary and an explanation of its structure:

{
    "<consumer's team name>": {
        "metadata": { team matadata },
        "<application name>": {
            "metadata": { application metadata },
            "services": {
                "<service name>": [
                    { service item's declaration }
                ]
            }
        }
    }
}
  • Top Level:
    • The top level of the dictionary represents the consumer's team name defined in NetOrca. In the example below, it is AwesomeCustomer
  • Consumer Level:
    • Consumer's metadata: The json contains consumer's metadata. Some services might require mandatory key values. (Please see Team and Application Metadata)
    • Each application is defined under the consumer's level along with consumer's metadata. The key is the application name, and the value is application's declaration
    • In the example below, the name of the application is NewApp1
  • Application Level:
    • Application's metadata: Similar to the consumer's metadata, this json provides specific information about the application. Some services might require mandatory key values. (Please see Team and Application Metadata)
    • services: The services section contains all the service items required for the application.
  • Service Level:
    • In this dictionary, the key is the name of the service defined in Service Catalog in NetOrca, and the value is an array of dictionaries, and each dictionary represents one service item's declaration.
    • In the example below, the service items are requested from 3 services: VM, LoadBalancer, and NetworkPattern

Here in a full example of a declaration: 

{
  "AwesomeCustomer": {
    "metadata": {
      "budget_code": "BC12345",
      "team_email": "email@gmail.com"
    },
    "NewApp1": {
      "metadata": {
        "application_ci": "NewApp ServiceNow ID",
        "paas_route": "newapp"
      },
      "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",
            "LoadBalancer": "CoreLB1"
          }
        ]
      }
    }
  }
}

Metadata

It is possible that NetOrca itself defines a JSON schema for both team and application metadata dictionaries. Also, the Service Owner are able to make some of the key values in Team and Application Metadata required for their services. Therefore, if you want to request service items from their service, you should include their required key values in your team and/or application metadata.

Other Ways of Submission

In addition to submission directly via endpoints or using the Python SDK, there are two ways to build and submit declarations. These methods are particularly useful when dealing with size of declarations or when consumers prefer to maintain tracking, supervision, and approval process for their final submissions:

GitOps

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

We highly recommend setting up a git repository to manage the declarations that your team submits. NetOrca provides the prebuilt CI/CD scripts to validate and submit your declarations. Please visit the GitOps page to set up your Git repository.

Submission Builder in GUI

It is also possible to build and submit the declaration through GUI. Users who are not familiar with YAML and JSON formats, are often confused with preparing the declaration files. They may also not know how to use git. Or their organization may not have a private git project. Also, for some consumers, the declaration might be small that it is not worth it to set up a git repository. To cover such problems, NetOrca provides Submission Builder Wizard in on the website. Consumers can modify or build the declarations from scratch and keep everything on NetOrca's database. Please visit Submission Builder Page to learn more.

More Features

Dry Run

It is possible to validate the consumer's declaration in dry_run mode. The validation HTTP request must be sent with dry_run=true as GET parameter, and if the validation is successful, you will receive the list of change instances that are going to be generated if you submit the declaration.

  • An example:
POST /v1/orcabase/consumer/submissions/validate/?dry_run=true HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY>

{
  "consumer1": {
    "app1": {
      "metadata": {
        "env": "dev",
        "application_ci": "CI123456"
      },
      "services": {
        "VM": [
          {
            "name": "vm1",
            "cpu": 2,
            "ram": 8
          }
        ]
      }
   }
}

And the response contains the change instances with following json schema

{
  "is_valid": true,
  "errors": {},
  "change_instances": [
    {
      "id": null,
      "state": "PENDING",
      "change_type": "CREATE",
      "log": "",
      "service_item": {
        "id": null,
        "name": "vm1"
      },
      "service": {
        "id": 1,
        "name": "VM"
      },
      "application": {
        "id": null,
        "name": "app1"
      },
      "new_declaration": {
        "version": 1,
        "declaration": {
          "cpu": 2,
          "name": "vm1",
          "memory": 8
        }
      },
      "service_owner_team": {
        "id": 1,
        "name": "team_owner_vm"
      }
    }
 ]
}

Partial Submission

For submissions with extensive declaration and a large number of applications, it's common to add new or modify just a few applications after the initial submission. To handle these changes efficiently, we use partial submissions. This approach allows you to submit only the new or modified applications, rather than resubmitting the entire declaration. In the validator's logic, when a declaration is partially submitted, everything is validated the same as with a full submission except that it skips deleting applications not included in the partial declaration.

To submit, or validate, partially, the request must be sent to the same endpoint, i.e. /v1/orcabase/consumer/submit/ or /v1/orcabase/consumer/validate/ , but with the PATCH method. The declaration structure is the same as a complete submission. However, it contains only the new and modified apps.

  • An example:

First, the initial complete submission contains 4 apps: NewApp1, NewApp2, NewApp3, and NewApp4. So, the body of the request to the endpoint is:

POST /v1/orcabase/consumer/submissions/submit/ HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY>
{
    "Consumer1": {
        "metadata": {...},
        "NewApp1": {...},
        "NewApp2": {...},
        "NewApp3": {...},
        "NewApp4": {...}
    }
}

Now, for the partial submission, the request must be sent to the same endpoint, but with the PATCH method. The declaration structure is the same as a complete submission. However, it contains only the new and modified apps. For example, let's modify NewApp1 and NewApp2 and create a new app called NewApp5. The body of the patch request would be:

PATCH /v1/orcabase/consumer/submissions/submit/ HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY>
{
    "Consumer1": {
        "NewApp1": {...}, // modified
        "NewApp2": {...}, // modified
        "NewApp5": {...} // new application
    }
}