Robot Roles
You can create robots (also known as service accounts) to automate deployments and other tasks in your CI system.
While you cannot assign roles statically to humans (human roles expire after a certain time), you can statically assign roles to robots/service accounts using the UI or the
wf assign
CLI command.
You can see details of a role by clicking the role name in the UI, or by running the CLI command: wf get accessrole ROLE-NAME -o yaml
. Use the -t
flag to specify a workspace other than your default workspace.
For more information, see wf get accessrole
.
This topic shows how to create a robot and assign it a role (such as cluster.deployment
, which lets the robot deploy applications in a specific namespace).
Create a robot​
To create a build robot/token for a workspace:
In your workspace, navigate to User access > Robots.
Click Create robot, fill in the Robot name and Robot description, and then click Next.
Click Select role for the role(s) you want to assign, and then click Next.
In the Set parameters form select the parameters required by the role(s) you've assigned to this robot, and then click Next.
The next page displays this robot's environment variables.
Click Copy to clipboard to copy the robot token and environment variables to use in CI, and then click Close.
Note
You will not be able to see or copy the environment variables once you click Close, but you can regenerate a robot token later. See Regenerate a robot token.
CLI: wf create robot
. See the example below.
Assign roles to robots after creation​
If you created a robot but did not assign it any roles, you can do so later.
To assign a role to a robot after it's been created:
- In your workspace, navigate to User access > Robots, and then find the robot you want.
- Click Assign roles, select the role(s) you want to assign, and then click Next.
- Select the parameters associated with the role(s) you selected, and then click Save.
CLI: wf assign
Regenerate a robot token​
You may need to regenerate a robot token for an existing robot if you did not copy environment variables when creating that robot for CI.
To regenerate a robot token:
In your workspace, navigate to User access > Robots, and find the robot you want a new token for.
Click Regenerate token for this robot, and then confirm.
If you have used the old token, for example in a CI system, you must replace all occurences of the old token with the new one.
CLI: wf create robot-token ROBOT-NAME --regenerate
Use the robot token​
You can use the robot token and secrets as shown below.
Use the robot token and run the build in CI​
For detailed information on adding environment variables in two popular CI systems, see:
To download and install the Wayfinder CLI, see Get the CLI.
Use the robot to access a cluster via kubeconfig​
You can exchange a robot token for a short-lived access token to access a cluster. To do this, you create a robot and assign it the cluster.deployment
role, use the environment variables generated for the robot in your CI system, and then run wf kubeconfig
as shown below.
# Create a robot and assign it the cluster.deployment role
$ wf create robot <NAME> ..
# Or if the robot already exists you can assign a role
$ wf assign cluster.deployment --robot <NAME>
...
# Use the robot account in CI pipeline - assuming you have taken the WAYFINDER_TOKEN,
# WAYFINDER_SERVER and WAYFINDER_WORKSPACE environment variables from the robot. You can download the Wayfinder CLI from
# https://docs.appvia.io/wayfinder/releases or use docker image quay.io/wayfinder/cli:<VERSION>.
# Provision a kubeconfig configuration file to speak to the cluster.
$ wf kubeconfig --cluster <NAME>
# Run kubectl commands as needed for the cluster
$ kubectl [commands]
Example: Create a robot and assign it a role​
In this example, you need a robot for CI to build and deploy an application into the namespace. To do this, you will create a robot and then assign it permissions.
In this example, you create a robot named app1
.
To create a robot:
Run the following:
$ wf create robot app1 --show-config
✔ Please provides a description of use for this account: Robot used to deploy application 1█
feature-gates:
application_services: true
monitoring_services: false
services: true
profiles:
default:
server: default
workspace: devs
user: default
servers:
default:
server: http://localhost:10080
users:
default:
wf-identity:
refresh-token: <TOKEN>
version: latestNote
--show-config
provides a convenience method producing a Wayfinder CLI configuration that can be copied as a whole into your chosen CI as a secret, or placed in a local file to test the robot.
To assign permissions to the robot:
Run
wf assign
, select the role and the robot, and respond to the prompts for parameters. The parameters depend on the role selected. Example:$ wf assign
? Which role would you like to use?
â–¸ cluster.deployment
Name:cluster.deployment
Owner:devs
Provides a deployment permission set which can be used by robot
accounts to deploy their applications in a namespace.
Note the policy is intentionally locked down per namespace, per
cluster to ensure use of a different token per application.In this example, you selected the
cluster.deployment
role, and the robot accountapp1
to assign the permissions to. Two parameters are required for this role, thecluster
andnamespace
. Example response:$ wf assign
✔ You have choosen the role: "cluster.deployment"
✔ Policy will apply to robot: app1
✔ This role has a number of 2 parameters associated
â—‰ The role has a required value: "cluster" (single)
✔ You have selected eks-dev as the cluster:
â—‰ The role has a required value: "namespace" (single)
✔ You have selected test as the namespace:
Plan has been successfully assigned to subject/sAt this point the permissions are assigned to the robot.
To verify the policy assigned to this robot, run either of the following commands:
wf get accesspolicy --robot ROBOT-NAME
(mini view)wf get accesspolicy --robot app1 --all
(detailed view)Example:
$ wf get accesspolicy --robot app1
NAME COMPLIANCE PLAN ENABLED STATUS AGE
cluster.deployment-assign-d5q7x none cluster.deployment true Success 11m
# See all policies attached, including policies generated by the application of the role, using
# --all:
$ wf get accesspolicy --robot app1 --all
NAME COMPLIANCE PLAN ENABLED STATUS AGE
cluster.deployment-api-p2bbg default - true Success 12m
cluster.deployment-assign-d5q7x none cluster.deployment true Success 12m
cluster.deployment-clusterwide-ps86l default - true Success 12m
cluster.deployment-namespace-7g95c default - true Success 12mNote
The mini view provides just the assignment: The policy
cluster.deployment-assign-d5q7x
references the rolecluster.deployment
. The detailed view shows how these parameters explode out into three separate policies targeting the Wayfinder API, the selected cluster, and the selected namespace.