SearchVarnish Controller
Private agents and routers is a concept that makes these components private to an organization in
Varnish Controller. Agents and routers that are started with a so-called private token are bound to the organization
but could also be shared with other organizations via a shared token.
A shared token is generated based on a private token. When a different organization takes use of the
shared token, the organization also gains access to the private agents or routers that use the private token that
the shared token references.
An agent that is started with a private token and has a VCLGroup deployed as root, cannot be shared. It is also not possible to deploy a VCLGroup as root onto a shared agent. This is to avoid collisions between usage of agents in a shared environment, since a root deployed agent cannot be used for deployment of any other VCLGroups.
Both organizations and system admin can create private tokens and share these with organizations.
In order to start an agent or router with a private token, we need to first generate a private token using either API, CLI or GUI.
Using the vcli it is a simple as the following example:
vcli pt add MyPrivateToken
The generated private-token (PRIVATE-<identifier>) is then used to start agents and routers. Multiple private tokens
can be generated. Agents and routers can share the same token or use different ones. It is up to the user to decide. Note that
adding a shared token to reference the private token, will give access to all the routers/agents that use the private token.
Some use cases of private tokens:
The figure above shows the following scenario:
Org1 has created a private token and started a couple of agents and routers.Org1 has created a shared token based on the private token and shared this with org2.Org2 has used the shared token to gain access to org1 agents and routers.Org2 has created a private token and started agents and routers with this token. No shared token has been created and org2 is the only one with
access to these private agents and routers.As an organization user, there is basically nothing to consider when deploying a VCLGroup when using private/shared tokens. Tags can be added to any of these agents/routers and the VCLGroup will be deployed to any of these based on the tags. Just as without tokens. The system will make sure it only deploys the VCLGroup to the components that the organization has access to.
An agent started with a private token will be shown as private for the system admin or organization that owns the private token that the agent has
been started with. As long as there are no shared token for this private token, only the owner of the agent can use this agent to deploy
VCLGroups to.
Same goes for routers. It will be shown as private for the owner of the router. It will only use deployments from the owner as long as
it is not shared to other organizations. The router will only receive information for agents that are accessible by the organization.
Example output of the vcli from a system admin perspective:
$ vcli agent ls
+----+--------+-----------------+----------+---------------+--------------+-----------------+------+
| ID | Name | Access Level | State | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+--------+-----------------+----------+---------------+--------------+-----------------+------+
| 1 | agent3 | system | Running | 172.25.255.44 | 8083 | plus-6.0.10r1 | |
| 2 | agent2 | system | Running | 172.25.255.42 | 8082 | plus-6.0.10r1 | |
| 3 | agent6 | system | Down | 172.25.255.41 | 8081 | plus-6.0.10r1 | |
| 4 | agent4 | system | ReadOnly | 172.25.255.45 | 8084 | plus-6.0.10r1 | |
| 6 | agent5 | private(system) | Down | 172.25.255.46 | 8081 | plus-6.0.10r1 | |
| 7 | agent1 | private(org1) | Running | 172.25.255.48 | 8081 | plus-6.0.10r1 | |
+----+--------+-----------------+----------+---------------+--------------+-----------------+------+
The table output shows four agents started as system global agents, that any user/organization can take use of. Then there are two private agents. agent5 that is
owned by the system (system admin). agent1 is owned by the organization org1.
If a private token is deleted, it cannot be re-created. This means that the agents/routers that were using this private token, must be restarted with a new private token. Any shared token that was referencing the deleted private token will be deleted as well. Hence, all shared users will lose access to the agents/routers.
A shared token cannot be re-created. This means that deleting a shared token as an owner, will revoke access for the organizations using the shared token. This will lead to undeploy of the agents/routers associated with the shared token for the organizations. Access will not be granted until a new shared token has been generated and handed over to the organizations.
An agent or router that is started with a new private token, will be seen as a new agent or router by the Varnish Controller. Hence, changing the private token
for an agent or router will result in a new agent/router. The agent and router is unique to the Varnish Controller based on the private token ID and the specified name. The
private token ID is baked into the private token ID. The same goes for restaring an agent or router without a private-token. Then it will become a system available.
Names of agents/routers must be unique when started as system available (without private token).
Names of agents/routers must be unique when started with the same private token. Names can be the same if the private token differs between them.
Deleting a private token from the system will make the agents/routers using this fail to register to brainz. All deployments to these agents/routers will stop working. Be very careful when deleting private tokens from the system.
System admins cannot use shared tokens (they have full access already)
$ vcli pt add MyToken
+----+---------+--------+---------+-----------------------------------------------------------------+---------------------+---------------------+----------------+---------+
| ID | Name | Agents | Routers | Token | Created | Updated | Organization | Creator |
+----+---------+--------+---------+-----------------------------------------------------------------+---------------------+---------------------+----------------+---------+
| 1 | MyToken | | | PRIVATE-GEAX2AMGW2RRKQZL3HNJVKGN6FOBBPUIGOMIOFTLOMVB6CPTDLVGSKI | 2022-09-06 13:39:52 | 2022-09-06 13:39:52 | [System Admin] | test(1) |
+----+---------+--------+---------+-----------------------------------------------------------------+---------------------+---------------------+----------------+---------+
# Via command line flag:
varnish-controller-agent -private-token PRIVATE-GEAX2AMGW2RRKQZL3HNJVKGN6FOBBPUIGOMIOFTLOMVB6CPTDLVGSKI
varnish-controller-router -private-token PRIVATE-GEAX2AMGW2RRKQZL3HNJVKGN6FOBBPUIGOMIOFTLOMVB6CPTDLVGSKI
# Or via environment variable
VARNISH_CONTROLLER_PRIVATE_TOKEN=PRIVATE-GEAX2AMGW2RRKQZL3HNJVKGN6FOBBPUIGOMIOFTLOMVB6CPTDLVGSKI
When sharing access to a agent or router it will allow the organization of the shared token to take use of this agent or router as long as the shared token exists. As a shared token owner, the shared token can at any point be revoked (deleted). Once revoked, it must be generated again and the same token will not be possible to reproduce. Meaning that all users of a shared token must get the new token to once again gain access to the previously shared agents/routers.
A user of a shared token can also revoke their access, but as long as the same shared token exists, they can add it back to take use of it again. This means that a user who is using someone else’s shared token can remove it, but it will not be removed from the system. Only for the user that removed it. But if the shared token is removed by the owner of the shared token, it will be removed from the system and from all users that used it.
Multiple shared tokens can be generated for one private token. These can then be given to different organizations.
Example of creating a shared token based on a private token:
# Assuming we have a private token with ID 1
$ vclist add MyShared 1
+----+----------+--------+---------+---------------------------------------------------------------+-------+----------+---------------+---------------------+---------------------+----------------+---------+
| ID | Name | Agents | Routers | Token | Users | Owner | Private Token | Created | Updated | Organization | Creator |
+----+----------+--------+---------+---------------------------------------------------------------+-------+----------+---------------+---------------------+---------------------+----------------+---------+
| 1 | MyShared | | | SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y | 0 | [system] | (1)MyToken | 2022-09-06 14:26:23 | 2022-09-06 14:26:23 | [System Admin] | test(1) |
+----+----------+--------+---------+---------------------------------------------------------------+-------+----------+---------------+---------------------+---------------------+----------------+---------+
The token SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y is the one to share with other organizations.
The receiver of this shared token, will take use of it (to gain access to the agents/routers shared via this token):
$ vcli st use SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y
+----+----------+--------+---------+---------------------------------------------------------------+-------+----------+---------------+---------------------+---------------------+
| ID | Name | Agents | Routers | Token | Users | Owner | Private Token | Created | Updated |
+----+----------+--------+---------+---------------------------------------------------------------+-------+----------+---------------+---------------------+---------------------+
| 1 | MyShared | | | SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y | 1 | [system] | (1)MyToken | 2022-09-06 14:26:23 | 2022-09-06 14:26:23 |
+----+----------+--------+---------+---------------------------------------------------------------+-------+----------+---------------+---------------------+---------------------+
The access levels will appear differently depending on who is logged in to the system, they are individual between organizations. The access level is seen on the agent and router objects.
There are 3 types of access levels for agents/routers.
Listing private and shared tokens will reveal which routers/agents that are affected by the tokens. Also organizations that have access to the tokens will be listed.
By default, starting an agent or router without a private token, will make it fully available to all organizations. These are presented as system access levels. These are no
different from earlier versions of Varnish Controller where all organizations can use these agents and routers.
A shared access level means that the agent or router is being shared to your organization by another organization (or system admin). The access
to these can either be revoked by the user of them or the owner of them.
A private access level means that it’s private to the organization, it can still be shared to others, but the logged in user will see it as private if the agent
or router is theirs.
From version 6 of Varnish Controller, agents and routers can be transferred between organizations and back to the system. This is an operation that system administrators can perform in runtime. There is no need to restart the given component. It is however important to understand the implications. If there are deployed VCLGroups on the given agent/router, these might be undeployed if the deployed VCLGroup can no longer be deployed to the agent/router due to ownership change.
The transfer can be performed using a pre-created private token, or let the system generate a new private token for the target organization.
Transfer agents:
# 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
# Transfer from organization back to system wide
$ vcli agent transfer -o 0
Transfer routers:
# With an existing private-token
$ vcli router transfer -o <org_id> -p <private_token_id>
# Generate a new private token for the organization
$ vcli router transfer -o <org_id
# Transfer from organization back to system wide
$ vcli router transfer -o 0