Skip to main content

Set up a production-ready Kubernetes environment

This guide walks you through preparing your environment and deploying a Kubernetes custom scope in a production-ready setup using nullplatform.

Before you begin​

Make sure you have the following tools installed:

1. Install the nullplatform agent chart​

To install the nullplatform agent chart:

  1. Create an API key to install all the custom scope specifications.

    • In the platform UI, go to Platform settings > API keys, and click + New API key.
    • Select the account resource where the API key's roles will be assigned.

    ⚠️ Important: Roles must be assigned at the account level or the setup won’t work.

    • Select the required roles: ops, and secops.
    • Save your API key somewhere safe—you'll need it shortly.

  2. Add the Helm repository so you can install the charts:

    helm repo add nullplatform https://nullplatform.github.io/helm-charts
    helm repo update

  3. Set the environment variables:

    In this guide, we use the default agent tag: "environment:development". If you want to use different tags, just follow this format: "your_key1:your_value1". (you can also add more, separated by commas: "env:prod,team:secops").

    export NP_API_KEY=<your_api_key>
    export AGENT_TAGS="environment:development"
    export GITHUB_REPO=nullplatform/scopes

    💡 Tip: Save your agent tags—you’ll need them again later.

  1. Install the agent chart:

    helm install nullplatform-agent nullplatform/nullplatform-agent \
    --set configuration.values.NP_API_KEY=$NP_API_KEY \
    --set configuration.values.TAGS="$AGENT_TAGS" \
    --set configuration.values.GITHUB_REPO=$GITHUB_REPO
    Reference docs

Verify the agent installation​

Let’s make sure everything is working properly.

Check the agent in the UI

  1. Grab the agent ID from the install logs. It looks like this: "id\":\"123b245d-6e7b-4c56-d78e-12f34b50\"
  2. In the platform UI, go to Platform settings > Agents.
  3. You should see your new agent listed by that ID.

Check that the repo is installed

Run this command:

kubectl exec <<nullplatform-agent-pod>> -n nullplatform-tools -- ls /root/.np

You should see the path to the repository: @nullplatform.

2. Clone the scopes repository​

Open a new terminal and clone the scopes repo:

git clone https://github.com/nullplatform/scopes.git
cd scopes

This repo includes:

  • A base implementation of a Kubernetes scope
  • Utility scripts for configuration and cluster setup

You'll use this directory for the next steps.

3. Create a new API key with full agent permissions​

Create a new API key that gives your agent the permissions it needs to connect to nullplatform.

  • Go to Platform settings > API keys, and click + New API key.
  • Choose the account resource for role assignment.

⚠️ Important: Roles must be set at the account level or the setup won’t work.

  • Assign the following roles: agent, developer, ops, secops and secrets-reader.
  • Save the key—you’ll use it soon.

4. Set scope environment variables​

Set these environment variables for scope configuration:

export NP_API_KEY=<your_api_key_here>
export NRN=<your_resource_nrn>
export REPO_PATH=/root/.np/nullplatform/scopes
export SERVICE_PATH=k8s
export ENVIRONMENT=environment:development

What each variable does:

  • NP_API_KEY: Your API key with agent-level roles.
  • NRN: Your resource's NRN (you’ll find it in the platform UI).
  • REPO_PATH: Path where the scope repo is installed. For the scopes repo, it must be /root/.np/nullplatform/scopes.
  • SERVICE_PATH: Path to the scope implementation, e.g., k8s if you're using our scopes.
  • ENVIRONMENT: Environment where the agent runs.

ℹ️ Important: The ENVIRONMENT value must match your earlier AGENT_TAGS (e.g., "environment:development").

5. Configure the custom scope​

Time to set up the core components of your custom scope. The configuration script:

  • Registers the JSON schema that defines the scope’s parameters.
  • Creates action specs, like create-scope, delete-scope.
  • Sets up a notification channel so your agent can receive events.

Run the command:

./configure

You should see this confirmation:

✔ The custom scope setup process completed successfully.

Confirm the custom scope is ready​

To verify that everything is set up correctly, check that the channel was created:

  1. Go to Platform settings > Channels.
  2. Filter by the resource name you set as NRN (e.g., my_cool_application).

You should see a newly created channel associated with your custom scope.

6. Create your first scope​

To test the setup, create a new scope:

  1. In the platform UI, go to your application and open the Scopes view.
  2. Click + New scope.
  3. Choose your new custom scope (look under target).

    Note: The default name is NKS.

  4. Fill in the config details and click Create scope.

That’s it! Your custom scope is live.

More resources​

Need help or want to go deeper?