Skip to main content
Version: 1.6

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:

  1. In your workspace, navigate to User access > Robots.

  2. Click Create robot, fill in the Robot name and Robot description, and then click Next.

  3. Click Select role for the role(s) you want to assign, and then click Next.

  4. 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.

  5. Click Copy to clipboard to copy the robot token and environment variables to use in CI, and then click Close.


    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:

  1. In your workspace, navigate to User access > Robots, and then find the robot you want.
  2. Click Assign roles, select the role(s) you want to assign, and then click Next.
  3. 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:

  1. In your workspace, navigate to User access > Robots, and find the robot you want a new token for.

  2. 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
# or use docker image<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:

  1. Run the following:

    $ wf create robot app1 --show-config
    ✔ Please provides a description of use for this account: Robot used to deploy application 1
    application_services: true
    monitoring_services: false
    services: true
    server: default
    workspace: devs
    user: default
    server: http://localhost:10080
    refresh-token: <TOKEN>
    version: latest

    --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:

  1. 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


    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 account app1 to assign the permissions to. Two parameters are required for this role, the cluster and namespace. 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/s

    At this point the permissions are assigned to the robot.

  2. 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)


    $ wf get accesspolicy --robot app1
    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
    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 12m

    The mini view provides just the assignment: The policy cluster.deployment-assign-d5q7x references the role cluster.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.