Create custom scopes

Custom scopes let you extend nullplatform to create environments that are not natively provided. For example, you can create a custom scope to deploy PL/SQL, static frontends, or an on-premise banking core.

Key features and concepts

Custom scopes are designed with these features and tenets:

• There's no distinction in our UI between custom and native scopes.
• All scope-centric features (like parameters, approvals, and policies) also apply to custom scopes.
• The forms to create and edit scopes can be customized to include parameters specific to your business needs.

Custom scopes vs. services

Custom scopes are (a subset of) services, so you can expect a common ground between these two.

• Scopes are execution units that live inside an application and are associated with a specific lifecycle and sets of actions, particularly with a deploy action.
• Services support a broader lifecycle that's independent of the applications they are created or linked to.

Have these criteria in mind when deciding if you'll be implementing a service or a custom scope.

How to create a custom scope

Follow these steps to set up your custom scope:

1. Create the scope service

To set up a custom scope:

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

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

POST /service_specification
{
    "name": "My scope name",                          
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2" // replace with a real NRN
    ],
    "created_at": "2024-10-29T03:41:54.822Z",
    "updated_at": "2024-10-29T03:41:54.822Z",
    "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"
    }
}

Notes:

• 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 December 16, 2024, optional parameters are not displayed in the UI but can still be configured using the API.

2. Implement lifecycle actions

Implement the callbacks that nullplatform will invoke at each step of the scope's lifecyle.

Name	Action type	Parameters	Description	Required
Create scope	create	scope_id	Triggered during scope creation to provision infrastructure independent of app versions (e.g., DNS).	Yes
Start initial	custom	scope_id, deployment_id	Starts an initial deployment, typically the first or after a scope restart.	Yes
Start blue green	custom	scope_id, deployment_id	Initiates a blue-green deployment.	Yes
Switch traffic	custom	scope_id, deployment_id, desired_traffic	Adjusts traffic percentage during blue-green deployments.	No
Finalize blue green	custom	scope_id, deployment_id	Cleans up old infrastructure after blue-green deployment completion.	Yes
Rollback deployment	custom	scope_id, deployment_id	Reverts a blue-green deployment by removing the new deployment's infrastructure.	Yes
Delete deployment	custom	scope_id, deployment_id	Deletes infrastructure for an active deployment when a scope is stopped.	No
Update scope	update	scope_id	Updates the scope’s infrastructure if changes are required.	No
Delete scope	custom	scope_id	Deletes app-version-independent infrastructure during scope deletion.	Yes

The execution order of these actions is illustrated below:

Example: Here’s the request body for the Finalize blue green action.

POST /service_specification/$service-spec/action_specification
{
    "name": "Finalize blue green",
    "type": "custom",
    "created_at": "2024-08-02T19:32:57.793Z",
    "updated_at": "2024-10-01T20:46:48.437Z",
    "parameters": {
        "schema": {
            "type": "object",
            "required": ["scope_id", "deployment_id"],
            "properties": {
                "scope_id": {
                    "type": "string"
                },
                "deployment_id": {
                    "type": "string"
                }
            }
        },
        "values": {}
    },
    "results": {
        "schema": {
            "type": "object",
            "properties": {}
        },
        "values": {}
    }
}

3. Register the custom scope

After defining your scope as a service, register it using the scope_type endpoint.

POST /scope_type
{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "type": "custom",
    "name": "K8S custom",
    "status": "active",
    "description": "Kubernetes by custom scope",
    "provider_type": "service",
    "provider_id": "a93b4440-a93b-4440-9f97-53c888b"
}