Getting started with Judoscale on Northflank

Connecting Northflank starts with a team-scoped API token. That token belongs to one Northflank team, and that team becomes one Judoscale team. After you connect, Judoscale lists a project environment for each project and stage that has a combined or deployment service. You choose which environments to link. A linked service with a public port is a web service. A linked service without one is a worker. Build services, jobs, and addons are left out.

Sign up for a Judoscale account and select “Northflank” for your hosting platform. Then create the token and connect the team.

Create a team API token

Judoscale binds one Judoscale team to one Northflank team. The token has to be team-scoped. Organization tokens are rejected, because they aren’t tied to a single team.

Before you create the token, create an RBAC role with these permissions. See Northflank’s Grant API access docs:

• Projects → Read
• Services → Read
• Services → Update

In Northflank, open Team → Tokens, create a token from that role, and name it “Judoscale” (you can name it anything you want). Copy the token right away—Northflank only shows it once.

Paste the token into Judoscale, and click “Connect to Northflank”.

Link a project environment

After connecting, Judoscale lists one entry for each project and stage that has a service it can scale. Names look like “Main Project - Production”. Services that aren’t assigned to a stage show up under “Default”, as in “Main Project - Default”.

Select the first project environment you want to link.

Linking a project environment creates a Judoscale application and lists its services. You’ll land on the team dashboard, where you can see each service, how many instances are running, and whether autoscaling is on. If this is your first time linking an environment, none will be autoscaling yet.

How Judoscale scales Northflank services

Judoscale uses the Northflank API to read your services, then updates the number of running instances when autoscaling is enabled. The scaling signal comes from the Judoscale package installed in your application, not from Northflank’s CPU, memory, or requests-per-second metrics.

For web services, Judoscale can scale on request queue time: how long requests wait before your application starts processing them. For worker services, Judoscale can scale on job queue time. This is especially important for I/O-heavy jobs, where a queue can back up even when CPU usage stays low.

Web vs worker detection

If a web service’s setup asks which queue to scale on, Judoscale is treating that service as a worker. On Northflank, a service is a web service when it has a public port, and a worker when it does not.

Open the application’s edit screen in Judoscale to confirm. Each linked service is labeled “web service” or “worker service”.

To fix a web service that was detected as a worker, add a public port in Northflank and refresh Judoscale after the next sync. If it still shows up as a worker, email us at [email protected] and we can correct it.

Installing the Judoscale package

In the Judoscale team dashboard, click the service you want to autoscale. This takes you to the Scaling page, where you’ll be prompted to complete the setup for that service.

Choose your stack information, and follow the instructions to install the package specific to your stack. The adapter package is how Judoscale collects metrics from your application, similar to a lightweight APM tool. Check the web frameworks and job backends we currently support here.

Once you’ve selected your stack, Judoscale shows the package install and a JUDOSCALE_URL value for that service.

The JUDOSCALE_URL environment variable is how the Judoscale package knows where to send metrics and link those metrics to the correct application. Add it to the service’s runtime environment, or to a secret group that the service uses. Most services in a project environment can share one value. If you have more than one web service, later web services get their own URL. See Making sense of your JUDOSCALE_URL env vars.

Deploy the service after setting the variable so the running instances pick it up. Then click “Finished and Deployed”. Judoscale will begin showing your queue metrics in the Scaling page charts.

Configuring and enabling autoscaling

Now that Judoscale is monitoring your service, you’re ready to autoscale!

Scroll down the Scaling page to review your autoscale settings. The default settings are usually a good starting point for most services, but you’ll want to customize your “Instances” range based on how high and low you’re comfortable scaling.

There’s no “correct” range here. Judoscale defaults to the initial scale as the minimum, to avoid downscaling as soon as autoscaling is enabled. Some teams are okay with having a single instance running under light load, while others always want multiple instances running, and they’ll set the minimum to two or higher. The maximum is really about limiting costs. Remember that under heavy load (high queue times), Judoscale will continue scaling your service up until the max instances is reached.

Scroll down and click “Save and enable autoscaling”, and that’s it!