Manage Deploy Permissions in YAML

You can specify and maintain global permissions, roles, and users for Deploy in YAML, enabling you to manage this aspect of your Deploy configuration "as code".

You can also manage local (folder-level) permissions in Deploy. See Local permissions in YAML for more information.

Before you begin

In Deploy, you can assign internal users to roles that determine the global permissions that they have. Global permissions apply across the entire Deploy system.

You should familiarize yourself with how global permissions and roles work in Deploy:

• Roles and permissions
• Configure roles and permissions

Work with users

This section describes how to define internal users in YAML, view the results in the UI, and then generate YAML that reflects your configuration.

Define users in YAML

To support running the examples shown in this topic, define three users.

Create a YAML file with the following specification:

---
apiVersion: xl-deploy/v1
kind: Users
spec:
- username: chris_smith
  password: !value pass1
- username: jay_albert
  password: changeme
- username: sue_perez
  password: changeme

Save the file (e.g., create-users.yaml) and apply it to Deploy:

xl apply -f create-users.yaml

Go to UI and confirm the results.

Generate YAML for users

You can generate a YAML file that specifies your users by using the xl generate command with the -u flag.

xl generate xl-deploy -u -f users.yaml

Example of output results:

---
apiVersion: xl-deploy/v1
kind: Users
spec:
- username: admin
- username: chris_smith
- username: jay_albert
- username: sue_perez

note

The YAML output does not include the password information as it is encrypted.

Work with global roles

This section describes how to define global roles in YAML, view the results in the UI, and then generate a YAML file that reflects your configuration.

Define global roles in YAML

To support running the examples shown in this topic, define two roles (Leaders and Developers) with one or more users (referred to as principals) assigned to them.

Create a YAML file with the following specification:

---
apiVersion: xl-deploy/v1
kind: Roles
spec:
- name: Leaders
  principals:
  - jay_albert
- name: Developers
  principals:
  - ron_vallee
  - sue_perez

Save the file (e.g., create-roles.yaml) and apply it to Deploy:

xl apply -f create-roles.yaml

Go to UI and confirm the results.

Generate YAML for global roles

To generate YAML for your existing global role configuration to a file called roles.yaml, add the -r flag:

xl generate xl-deploy -r -f roles.yaml

Result:

---
apiVersion: xl-deploy/v1
kind: Roles
spec:
- name: leaders
  principals:
  - jay_albert
- name: developers
  principals:
  - ron_vallee
  - sue_perez

Work with global permissions

This section describes how to define global permissions and view the results in the UI. It also describes how to generate a YAML file specifying your global permissions.

Define global permissions in YAML

Similar to roles, you can define global permissions in YAML and apply to Deploy.

To define global permissions, create a YAML file and assign specific permissions to each role (Leaders and Developers).

This example grants all available permissions for the Developers role and limits the Leaders role to two permissions:

---
apiVersion: xl-deploy/v1
kind: Permissions
spec:
- global:
  - role: Leaders
    permissions:
    - report#view
    - task#assign
  - role: Developers
    permissions:
    - task#skip_step
    - admin
    - login
    - task#takeover
    - task#preview_step
    - report#view
    - discovery
    - controltask#execute
    - task#assign
    - task#view
    - task#move_step
    - security#edit

Save the file (e.g., global-perms.yaml) and apply it to Deploy:

xl apply -f global-perms.yaml

Review the results in the UI:

Generate YAML for global permissions

Generate YAML for your existing global permissions configuration to a file called permissions.yaml, add the -g flag:

xl generate xl-deploy -g -f permissions.yaml

Local permissions in YAML

Local permissions only apply to the folder level they are assigned to, and to all nested folders unless they are overridden by a folder permission below it. For more information and a list of all available local permissions, refer to Local permissions.

Create users and roles

We can use two of the existing users and roles that were created in the previous exercise:

• jay_albert - Leaders
• sue_perez - Developers

However we should update their global permissions:

---
apiVersion: xl-deploy/v1
kind: Permissions
spec:
- global:
  - role: Leaders
    permissions:
    - login
  - role: Developers
    permissions:
    - task#skip_step
    - admin
    - login
    - task#takeover
    - task#preview_step
    - report#view
    - discovery
    - controltask#execute
    - task#assign
    - task#view
    - task#move_step
    - security#edit

This will give jay_albert minimal system access, and full admin access to sue_perez.

Set up Applications and Environments with folders

Note: It is not currently possible to define permissions for a root node in YAML, such as Applications, Environments, Infrastructure, or Configuration. These should be managed in the GUI.

In the Deploy GUI, create the following new directories:

• Under Applications - Application Directory 1, with a sub-directory of Application Directory 2
• Under Environments - Environment Directory 1, with a sub-directory of Environment Directory 2

Generate the YAML for the directories:

xl generate xl-deploy -p Applications -ovf applications.yml
xl generate xl-deploy -p Environments -ovf environments.yml

Note: As in the above example, each root node of Deploy should be managed independently through YAML.

Open the YAML files. They will show the following text:

Applications

---
apiVersion: xl-deploy/v1
kind: Applications
spec:
- directory: Applications/Application Directory 1
  children:
  - directory: Application Directory 2

Environments

---
apiVersion: xl-deploy/v1
kind: Environments
spec:
- directory: Environments/Environment Directory 1
  children:
  - directory: Environment Directory 2

Set root node permissions in the GUI

Firstly, in the GUI create the following permissions: Applications

• Developers - control task execute, import initial, import remove, import upgrade, read, repo edit
• Leaders - read

Environments No permissions.

In a separate browser, log in with user jay_albert and with sue_perez. You will see that:

• jay_albert can view, but not interact with, all directories in Applications but cannot view anything in Environments.
• sue_perez can interact with and view all directories in Applications and Environments.

Define local permissions in YAML

In the two YAML files, add the following sets of permissions: Applications

---
apiVersion: xl-deploy/v1
kind: Applications
spec:
- directory: Applications/Application Directory 1
  children:
  - directory: Application Directory 2
---
apiVersion: xl-deploy/v1
kind: Permissions
spec:
- directory: Applications/Application Directory 1
  roles:
  - role: Leaders
    permissions:
    - import#initial
    - read
    - import#upgrade
    - controltask#execute
    - repo#edit
    - import#remove
- directory: Applications/Application Directory 1/Application Directory 2
  roles:
  - role: Leaders
    permissions:
    - read

Environments

---
apiVersion: xl-deploy/v1
kind: Environments
spec:
- directory: Environments/Environment Directory 1
  children:
  - directory: Environment Directory 2
---
apiVersion: xl-deploy/v1
kind: Permissions
spec:
- directory: Environments/Environment Directory 1/Environment Directory 2
  roles:
  - role: Leaders
    permissions:
    - read
  - role: Developers
    permissions:
    - read

Apply them again, and log in with the two users. You will see that:

• jay_albert can view but not interact with the directories in Environments.
• sue_perez can still interact with and view all directories in Applications and Environments.

From this scenario, you can see in a practical way the application of the rules described in How local permissions work in the hierarchy:

• Because jay_albert has only login permissions defined at a global level, he cannot interact with anything that is not strictly defined for read access at a minimum.
  • He can interact with nearly all elements in Application Directory 1, but he can only view the elements in Application Directory 2. The read permission overrode all the other permissions set in Application Directory 1.
  • His access to Environments is still fully restricted because although he has read access to Environment Directory 2, he has no access to the higher-level folder Environment Directory 1.
• Because sue_perez has full permissions defined at a global level, she can interact with all elements in the system, and will not be affected by changes to local permissions.
  • If a global permission is set, it will always take precedence over local permissions at all levels of the hierarchy.