Private Agents

Introduction

This tutorial will show how to setup private agents (and routers) using Private Tokens. It will also give examples on how to share these private components with other organizations in the Varnish Controller system.

This tutorial will re-use the files from the HTTP Routing tutorial found here: https://github.com/varnish/router_example

Environment

Requirements:

docker
docker-compose
git
A Varnish Controller License (with Router addon for router support).

The environment in this tutorial consists of a docker-compose that brings up the following services:

2x Varnish Enterprise Servers
2x Varnish Controller Agents
1x Router
1x Varnish Controller Brainz
1x Varnish Controller API-GW
1x NATS Server
1x HTTPd (origin server)
1x PostgreSQL (database)

The default login to Varnish Controller is username test and password test (specified in the docker-compose file). This user is a system admin user and can be used to access both the UI and the CLI.

Private Agents

Start by cloning the repository to a directory of choice:

$ git clone git@github.com:varnish/router_example.git
$ cd router_example

Add the Varnish Controller license file to the directory with the name router_license.lic.
Start the environment:
```
$ docker-compose up
```
Now stop agent-1. This agent will be restarted as a private-agent.
```
$ docker stop agent1
```

# Password is 'test'
$ vcli login http://172.31.0.206:8002 -u test
Configuration saved to: /home/user/.vcli.yml
Login successful.
# Generate a new private token
$ vcli pt add myToken
+----+---------+--------+---------+-----------------------------------------------------------------+----------------+---------+
| ID |  Name   | Agents | Routers |                              Token                              |  Organization  | Creator |
+----+---------+--------+---------+-----------------------------------------------------------------+----------------+---------+
|  1 | myToken |        |         | PRIVATE-GEA3O63BV2TA3KA3LJVG5DVGL5G43GKLKWRSHFFPETUNNAPWUNNCBRY | [System Admin] | test(1) |
+----+---------+--------+---------+-----------------------------------------------------------------+----------------+---------+
# List agents, we should now see 2 system-wide available agents (where agent1 is down, since we stopped it)
$ vcli agent ls
+----+---------+--------------+---------+--------------+--------------+-----------------+------+
| ID |  Name   | Access Level |  State  | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+---------+--------------+---------+--------------+--------------+-----------------+------+
|  1 | server1 | system       | Down    | 172.31.0.201 |         6081 | plus-6.0.10r1   |      |
|  2 | server2 | system       | Running | 172.31.0.202 |         6081 | plus-6.0.10r1   |      |
+----+---------+--------------+---------+--------------+--------------+-----------------+------+

Start agent1 with our previously generated private token and with a new name.

# Replace the token below, with your generated token.
$ docker-compose run -d -e VARNISH_CONTROLLER_AGENT_NAME=myAgent -e VARNISH_CONTROLLER_PRIVATE_TOKEN=PRIVATE-GEA3O63BV2TA3KA3LJVG5DVGL5G43GKLKWRSHFFPETUNNAPWUNNCBRY agent1

If we now list the agents, we can see a private agent, owned by system admin (hence system in parenthesis).

$ vcli agent ls
+----+---------+-----------------+---------+--------------+--------------+-----------------+------+
| ID |  Name   |  Access Level   |  State  | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+---------+-----------------+---------+--------------+--------------+-----------------+------+
|  1 | server1 | system          | Down    | 172.31.0.201 |         6081 | plus-6.0.10r1   |      |
|  2 | server2 | system          | Running | 172.31.0.202 |         6081 | plus-6.0.10r1   |      |
|  3 | myAgent | private(system) | Running | 172.31.0.201 |         6081 | plus-6.0.10r1   |      |
+----+---------+-----------------+---------+--------------+--------------+-----------------+------+

Only the owner of this private agent can deploy to this agent, except system admin that will have full access to all agents and routers. Other organizations can deploy to the private agent and router once it’s shared using a shared token.

We can share our previously started private agent with one or more organizations.

As the private token owner, in this case system admin, we create a shared token and reference our private token.

# The private token ID is 1
$ vcli st add myShared 1
+----+----------+------------+---------+---------------------------------------------------------------+-------+----------+---------------+----------------+---------+
| ID |   Name   |   Agents   | Routers |                             Token                             | Users |  Owner   | Private Token |  Organization  | Creator |
+----+----------+------------+---------+---------------------------------------------------------------+-------+----------+---------------+----------------+---------+
|  1 | myShared | myAgent(3) |         | SHARE-EEAQWDLC2M3KFSO3VWH5GO4SAK3WETGZB2YTTYXJQXWAKAHCOJCAZBI |     0 | [system] | (1)myToken    | [System Admin] | test(1) |
+----+----------+------------+---------+---------------------------------------------------------------+-------+----------+---------------+----------------+---------+

The generated shared token, will be handed over to a organization user, so they can use the referenced private agent. Let’s create an organization, a new user and assign the user to the organization.

# Add the org 'myorg'
$ vcli org add myorg

# Create the user 'myuser' with password 'test'
$ vcli acc add myuser --password test

# Assign user with ID 2 (myuser) to org with ID 1 (myorg)
$ vcli org assign 1 -a 2

Login with the new user and organization. Then take use of the shared token, which has been shared with the organization user.

# Login
$ vcli login http://172.31.0.206:8002 -u myuser -o myorg

# List agents (only 2 system agents should be visible)
$ vcli agent ls
+----+---------+--------------+---------+--------------+--------------+-----------------+------+
| ID |  Name   | Access Level |  State  | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+---------+--------------+---------+--------------+--------------+-----------------+------+
|  1 | server1 | system       | Down    | 172.31.0.201 |         6081 | plus-6.0.10r1   |      |
|  2 | server2 | system       | Running | 172.31.0.202 |         6081 | plus-6.0.10r1   |      |
+----+---------+--------------+---------+--------------+--------------+-----------------+------+

# Use the shared token
$ vcli st use SHARE-EEAQWDLC2M3KFSO3VWH5GO4SAK3WETGZB2YTTYXJQXWAKAHCOJCAZBI
+----+----------+------------+---------+---------------------------------------------------------------+-------+----------+---------------+
    | ID |   Name   |   Agents   | Routers |                             Token                             | Users |  Owner   | Private Token |
+----+----------+------------+---------+---------------------------------------------------------------+-------+----------+---------------+
|  1 | myShared | myAgent(3) |         | SHARE-EEAQWDLC2M3KFSO3VWH5GO4SAK3WETGZB2YTTYXJQXWAKAHCOJCAZBI |     1 | [system] | (1)myToken    |
+----+----------+------------+---------+---------------------------------------------------------------+-------+----------+---------------+

# List agents again, and the private agent should be visible and useable as it's now shared.
$ vcli agent ls
+----+---------+--------------+---------+--------------+--------------+-----------------+------+
| ID |  Name   | Access Level |  State  | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+---------+--------------+---------+--------------+--------------+-----------------+------+
|  1 | server1 | system       | Down    | 172.31.0.201 |         6081 | plus-6.0.10r1   |      |
|  2 | server2 | system       | Running | 172.31.0.202 |         6081 | plus-6.0.10r1   |      |
|  3 | myAgent | shared       | Running | 172.31.0.201 |         6081 | plus-6.0.10r1   |      |
+----+---------+--------------+---------+--------------+--------------+-----------------+------+

Once the shared token has been added, the organization can deploy VCLGroups to this agent (myAgent).

Transfer Ownership

Varnish Controller agents and routers can be transferred to and from organizations at runtime.

In the CLI we can transfer agent by specifying arg -o to set the organization ID, and the optional -p to use an existing private token.

# With an existing private-token
$ vcli agent transfer -o <org_id> -p <private_token_id>
# Generate a new private token for the organization
$ vcli agent transfer -o <org_id

In the UI we can transfer an agent or a router from the individual agent/router overview page /servers/<AGENT-ID> & routers/<ROUTER-ID>. Clicking the Transfer button will trigger a modal that will guide you through the process by selecting the destination organization, and the optional private-token to attach.

Transfer an agent in the UI

Only system administrators are able to transfer agents/routers to and from organizations.

Notes

Both system admins and organization users can generate private tokens and start private agents. The agents will only be visible and usable by the owner of the private token. Only if a shared token is created and given to other users, it will be usable by other organizations as well.
The same approach described in this tutorial can be used for Routers as well.
One or more agents and routers can be using the same private token. Generating a shared token for this private token would give access to all agents and routers that are using the private token which is attached to the shared token.
The user of the shared token can remove the shared token for its own organization, which basically means that it will stop using the agents and routers referenced by the shared token. It can be added back as long as the shared token owner hasn’t removed it.
If a shared token is removed by the owner of the shared token, organizations using this token will lose access to the agents and routers for the shared token.
Removing a private token will also remove all attached shared tokens for this private token.
There is no way of recreating a private token. Hence, agents and routers must be restarted with a new private token if the private token has been removed. They will then get new ID’s and will be seen as new agents and routers to the system. This is not relevant to transferred agents/routers that have private-tokens automatically assigned.
A private-token that is in use by agents or routers cannot be removed until no further agent/router is using it.

Cleanup

The docker-compose will create volumes for storing database and other configuration data. These can be cleaned up if you want to start from scratch.

# Stop environment
docker-compose down
# Remove volumes
docker volume rm router_example_dbdata router_example_varnish router_example_vcontroller

References

Tokens

Private Agents

Private Agents

Introduction

Environment

Private Agents

Sharing Agents

Transfer Ownership

Notes

Cleanup

References