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.

    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:

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

  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█
    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: latest
    Note

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

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

    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    12m
    Note

    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.

Last updated on 24 Oct 2022