Skip to main content

Overview and key concepts

Agent-backed scopes let you extend nullplatform to support custom deployment environments—like PL/SQL apps, static frontends, or on-prem systems. They rely on the nullplatform agent, which runs in your Kubernetes cluster and securely connects to the platform to carry out actions.

How it works​

Agent-backed scopes run using the nullplatform agent, which lives inside your Kubernetes cluster and listens for actions.

Here’s what happens under the hood:

  1. You define your scope using a spec and a set of lifecycle actions
  2. The scope is registered with your organization
  3. The agent listens for matching actions and sends them to your runner
  4. The runner provisions infra or executes commands as needed

You can read more about the nullplatform agent in our Agent docs.

Key concepts​

Here are the main building blocks of agent-backed scopes:

Specifications​

Each scope starts with a service specification (also known as "specs") that defines its structure:

  • Scope name, category, visibility
  • Parameters your scope will accept
  • Schema that defines the shape of input data

Think of it like a class definition. The scopes you create from it are the instances.

Here's an example of a agent-backed scope specification:

{
    "name": "My scope name",                          
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2"
    ],
    "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": "Agent backed scope"
    }
}

Lifecycle actions​

Actions define what you can do with a scope. Each action is defined through an action specification, which outlines the parameters and expected behavior.

Scopes support both standard actions (create, update, delete) and custom actions like rollback or switch_traffic.

Here's an example of an action spec:

{
    "name": "Create a scope",
    "type": "create",
    "created_at": "2024-08-02T19:32:57.793Z",
    "updated_at": "2024-10-01T20:46:48.437Z",
    "parameters": {
        "schema": {
            "type": "object",
            "required": ["scope_id"],
            "properties": {
                "scope_id": {
                    "type": "string"
                },
            }
        },
        "values": {}
    },
    "results": {
        "schema": {
            "type": "object",
            "properties": {}
        },
        "values": {}
    }
}
Actions and Action Specs are different things

In the same way you have service specs for scopes(~class) and scopes (~objects), you will have action specifications and concrete actions that have been created out of that specification.

Visibility​

You can limit which users or teams and use your scopes by setting visibility based on NRNs.

This helps you control scope availability across different parts of your organization.

Summary​

EntityDescription
Agent-backed scopeA scope instance created from a specification. Supports standard and custom lifecycle actions.
Scope specificationAlso referred to as service specification. Defines the name, category, visibility, and parameters for the scope it defines.
Action specificationDefines the type (create, update, delete, custom) of actions along its parameters.
ActionAn action instance executed through a runner to manage the scope's lifecycle.

Next steps​

Now that you understand the core ideas, choose where to go next: