Connect & authenticate

The orchestrator serves everything on one address inside the project's private network:

http://orch.<hostname>.zerops

For a Swarm service with the hostname sandbox that is http://orch.sandbox.zerops. The control API, the web UI at / and the API reference at /swagger all live there. The orchestrator has no public address.

Ways to connect

From	How	API token
Your workstation	Start the Zerops VPN and call http://orch.<hostname>.zerops, or open it in a browser for the UI.	Not needed
A service in the project	Call the same address over the private network.	Required
The Zerops GUI	Open the orchestrator UI from the service detail. Zerops creates a link that is valid for one hour and signs you in.	Added for you

From your workstation

Connect with zcli vpn up and use the API directly. Requests that come from the VPN skip the API token check, so there is nothing to configure:

curl -s http://orch.sandbox.zerops/container

From a service in the project

This is the usual setup: a backend, a CI runner or an agent in the same project drives the pool. It has to send the API token as a bearer token:

curl -s http://orch.sandbox.zerops/container \
  -H "Authorization: Bearer $SANDBOX_API_TOKEN"

Pass the token to your service by referencing the Swarm service's variable in its zerops.yaml:

zerops.yaml

zerops:
  - setup: api
    run:
      envVariables:
        SANDBOX_URL: http://orch.sandbox.zerops
        SANDBOX_API_TOKEN: ${sandbox_API_TOKEN}

From the GUI

The link from the service detail goes through a Zerops proxy that adds the API token to every request, so the UI works without the VPN. The proxy never adds the admin token. To force an action in the UI you enter the admin token there yourself.

The UI covers the whole API, including a shell to run commands, and is handy for watching what your code does with the pool.

Tokens

Both tokens are generated when the service is created. You find them in the service detail under Environment variables.

Variable	Sent as	What it allows
API_TOKEN	Authorization: Bearer <token>	Every call of the API. Whoever has it can create and remove containers and run commands in any container nobody else holds. Not required from the VPN.
ADMIN_TOKEN	X-Swarm-Admin-Token: <token>	Taking a container away from the consumer that holds it, with force=true. Required from the VPN too.

A pool is usually shared: every consumer has the API token, and a lease keeps them out of each other's containers. Breaking a lease kills somebody's work, so it takes a second secret, which you give only to operators and to the code that cleans up after crashed consumers.

You can check an admin token without doing anything with it:

curl -s http://orch.sandbox.zerops/admin/check \
  -H "Authorization: Bearer $SANDBOX_API_TOKEN" \
  -H "X-Swarm-Admin-Token: $SANDBOX_ADMIN_TOKEN"
# {"enforced":true,"configured":true,"admin":true}

What is open and what is not

• The UI files (/ and /ui/*) and the API reference (/swagger) are served without a token. They contain nothing about your pool.
• If you empty API_TOKEN, the API is open to everything that can reach it on the private network, and force needs no admin token either.
• If API_TOKEN is set and you empty ADMIN_TOKEN, every forced takeover is refused.
• The pool containers never see either token, as the code running in them could otherwise control the whole pool.

Change a token

Edit the variable in the GUI and then reload the Swarm service. The orchestrator reads its tokens when it starts, and a reload restarts it together with the start commands of the application you deployed to the pool, if any. It does not restart the pool containers, so it is the gentle option. A restart of the service works too, but restarts every container in the pool.

Reservations survive both. The orchestrator keeps them on disk.

SSH access to pool containers

The API is the intended way to run things in a pool container, and by default it is the only way available to your services. SSH access in Zerops is governed by SSH isolation, and its default, vpn, means:

• You can SSH from the VPN to any pool container, using the hostname the API returns for it. The web terminal in the GUI works too.
• No service in the project can SSH to a pool container, and pool containers cannot SSH to each other or to your other services.

If you want a service to SSH into the pool, allow it on the Swarm service:

zerops-import.yaml

services:
  - hostname: sandbox
    type: swarm@1
    sshIsolation: "vpn service@runner"

Warning

SSH does not know about leases. A service that is allowed to SSH into the pool can enter any container, including one another consumer has reserved, and the orchestrator cannot see or stop what it does there. Allow it only for services you would also trust with the admin token.