How-to guides for agent-backed scopes

These guides walk you through building, testing, and running your own agent-backed scopes in nullplatform—whether you're working locally or deploying to production.

Test scopes locally

Start by running a agent-backed scope on your local machine. This is a great way to learn how scopes work and validate that everything works before deploying it to a real cluster.

• Run a scope locally: A step-by-step guide to building, running, and validating a scope using the workshop scope repository.

Move to production

When you're ready to deploy your scope at scale, this guide helps you set up a production-ready Kubernetes environment. You’ll use the nullplatform agent and Helm to manage deployments.

• Set up a production-ready environment for a Kubernetes scope: Learn how to prepare your Kubernetes cluster for production using the starter scope repository as your base.

About the repositories

Both the workshop and starter repositories follow the same structure, so it’s easy to start locally and move to production with minimal changes.

Use them as a starting point and customize the structure to fit your scope’s needs.

scopes/
├── k8s/                        # Kubernetes-specific implementation
│   ├── scope/                  # Scope lifecycle actions
│   │   └── workflows/
│   │       ├── create.yaml
│   │       ├── update.yaml
│   │       └── delete.yaml
│   ├── deployment/             # Deployment actions
│   │   └── workflows/
│   │       ├── initial.yaml
│   │       ├── blue_green.yaml
│   │       └── ...
│   └── ...
├── service                     # Routes actions based on NP_ACTION_CONTEXT
├── agent/                      # Agent deployment scripts
├── configure                   # Configuration script
└── entrypoint                  # Main execution script

Key directories

Here's a quick overview of what’s inside:

• service/: Handles the logic for routing actions based on the NP_ACTION_CONTEXT environment variable.
• k8s/: Everything you need to deploy scopes and workflows in Kubernetes.
• agent/, configure/, and entrypoint/: Scripts and config files for running the scope.

Kubernetes workflows

In the k8s directory, you’ll find a workflows/ folder under each action type. These define how different components of the scope behave:

• scope/: Lifecycle actions like create, update, and delete.
• deployment/: Strategies like initial and blue_green.
• log/, metric/, and instance/: Optional add-on workflows.