Skip to main content

Custom scope specification

Custom scopes use service specifications to define their name, category, visibility, and allowed parameters.

Before you start

If you haven't done it yet, read about custom scopes' main concepts.

Also, have these handy references ready:

Design your scope service specification​

Before actually creating the custom scope, you have ask yourself some questions that we'll present in a table, so you can see how your answers impact your custom scope specification:

QuestionGuidance
What's the name for the custom scope?Choose a natural name (e.g., CronJob) and set it into the name field.
Which properties do I need to define for the scope?These are the properties that define the custom scope. They are usually a combination of input parameters plus values obtained from the cloud provider upon service creation. Set these as a JSON schema in the attributes field.
Where in the organization is the custom scope going to be available?A good default is to start by making the service visible everywhere with the value organization=your-org-id:account=*. Set your choice in the visible_to array.

Create the scope specification​

To set up a custom scope:

  • create a new service of type scope.
  • declare the type of asset it will deploy.

You can create a scope specification using our CLI or API.

Use the CLI wizard to speed things up 🚀

You can use our CLI wizard instead of writing API requests or standard CLI commands

Run the following command, and the wizard will guide you through each of the steps described below:

np scope-specification create --wizard

Here’s an example of a custom scope that accepts docker-image assets and includes a mandatory warmup parameter.

np service-specification create \
    --body '{
    "name": "My scope name",                          
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2" // replace with a real NRN
    ],
    "attributes": {
        "schema": {
            "type": "object",
            "required": [
                "warmup"
            ],
            "properties": {
                "asset_type": {
                    "type": "string",
                    "export": false,
                    "default": "docker-image",
                    "readOnly": true
                },
                "warmup": {
                    "type": "boolean",
                    "export": false,
                    "readOnly": false
                }
            }
        },
        "values": {}
    },
    "selectors": {
        "category": "Deployment Services",
        "imported": false,
        "provider": "AWS",
        "sub_category": "Custom Scope"
    }
}
Service details

The JSON schema under attributes determines the custom scope's attributes, fields and layout in the UI. These properties appear in the See details view in the nullplatform interface. You can further enhance the rendering of that section using UI Schema.

Some request details​

  • attributes: This field is mandatory and contains a JSON schema where you define:

    • the asset type for this scope.

    • the parameters that developers will have to set when creating or editing your scope.

    • asset_type: This parameter determines the types of assets that can be deployed to the scope.

      • Single-asset scopes: For scopes supporting a single asset type (e.g., docker-images), define asset_type as an optional parameter with a default value.
      • Multi-asset scopes: For scopes supporting multiple asset types, make the asset_type a required parameter so developers can select the type.

  • Additional parameters: You can include optional parameters in your custom scope configuration. Can be either:

    • required: Developers must provide values for these when creating a new scope.
    • optional: These can have default values and are not mandatory.
    info

    As of April 2024, optional parameters are not displayed in the UI but can still be configured using our API.